Context7 Platform -- Up-to-date docs for AI agents
CTX7-1760: Document GitOps for on-premise (#2816)
Fahreddin Özcan74dc6ba95c72
diff --git a/docs/docs.json b/docs/docs.jsonindex 46002eba..bf57e396 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -73,6 +73,12 @@"group": "On-Premise","pages": ["enterprise/on-premise",+ {+ "group": "Integrations",+ "pages": [+ "enterprise/integrations/github"+ ]+ },{"group": "Security","pages": [@@ -87,8 +93,14 @@"enterprise/deployment/kubernetes"]},- "enterprise/backup-restore",- "enterprise/library-import",+ {+ "group": "Features",+ "pages": [+ "enterprise/library-import",+ "enterprise/gitops",+ "enterprise/backup-restore"+ ]+ },{"group": "API Reference","pages": [diff --git a/docs/enterprise/gitops.mdx b/docs/enterprise/gitops.mdxnew file mode 100644index 00000000..1f91fc3d--- /dev/null+++ b/docs/enterprise/gitops.mdx@@ -0,0 +1,126 @@+---+title: "GitOps"+sidebarTitle: "GitOps"+description: "Manage the list of indexed repositories declaratively from a Git repo and reconcile your on-premise instance to match it"+---++GitOps lets you keep the list of repositories Context7 indexes in a Git repository, instead of adding them one by one in the dashboard. Context7 reads a manifest file from that repo and reconciles its own state to match: it indexes anything new, re-indexes anything whose settings changed, and (optionally) removes anything you have deleted from the manifest.++The point is to keep your configuration in code. After a disaster, or when standing up a second environment, you point a fresh instance at the manifest repository and the entire index rebuilds itself with no manual clicks.++<Frame>+ +</Frame>++## Before you start++GitOps clones your manifest repository and the repositories it indexes using the Git credentials you configure under **Settings → Integrations**. Connect a GitHub App or a personal access token first; see [GitHub Integration](/enterprise/integrations/github). Automatic syncs on every push require the **GitHub App** (a personal access token cannot receive webhooks).++<Warning>+If you set up the GitHub App **before** GitOps was available, it is not subscribed to push events and will not trigger syncs. Add the **push** event to the App on GitHub, or recreate it from **Settings → Integrations**. See [GitHub Integration](/enterprise/integrations/github#webhooks).+</Warning>++## How it works++You commit a manifest file (by default `repos.yaml`) to a Git repository. Context7 clones that repository using the same Git credentials you already configured under **Settings → Integrations** (a GitHub App or a personal access token), reads the manifest, and compares it against the repositories it currently has indexed.++For each repository in the manifest, Context7 decides what to do:++- **Add** it if it is in the manifest but not yet indexed.+- **Re-index** it if its manifest entry changed, for example a different branch or new folder filters, or if its last indexing run did not finish.+- **Leave it untouched** if it already matches. Running a sync with no changes is a safe no-op.++When pruning is enabled, repositories that you remove from the manifest are also deleted from the instance. Pruning only ever removes repositories that GitOps itself added; repositories you add by hand in the dashboard are never touched.++<Note>+GitOps is the source of truth only for the repositories listed in the manifest. You can still add other repositories manually in the dashboard, and they will be left alone during a sync.+</Note>++## The manifest file++The manifest is a YAML file with a list of repositories under `repos`. An optional `defaults` block applies to every entry unless an entry overrides it.++```yaml repos.yaml+defaults:+ indexSourceCode: false+ branch: "" # empty means the repository's default branch+repos:+ - url: https://github.com/acme/payments+ branch: main+ folders: [docs]+ excludeFolders: [node_modules]+ - url: https://github.com/acme/billing+ indexSourceCode: true+```++Each entry accepts the same options as the **Add Repository** form in the dashboard:++| Field | Description |+| ----- | ----------- |+| `url` (or `repoUrl`) | The Git repository to index. Required. |+| `branch` | Branch to index. Leave blank to use the repository's default branch. |+| `folders` | Only index these folders. Omit to index the whole repository. |+| `excludeFolders` | Folders to skip. |+| `excludeFiles` | File patterns to skip, for example `["*.test.md"]`. |+| `indexSourceCode` | Whether to also generate documentation from source code. Defaults to `false`. |++If the manifest cannot be parsed, the whole sync is rejected and nothing changes, so a malformed file can never partially apply or wipe your index.++## Configuring in the dashboard++Open **Settings → Indexing → GitOps**, fill in the manifest repository, and save.++| Setting | Description |+| ------- | ----------- |+| Enable GitOps sync | Turns on automatic reconciliation (on startup, on the schedule, and on push). When off, nothing syncs automatically, but you can still run a sync by hand. |+| Manifest repository URL | The Git repository that holds the manifest. |+| Manifest path | Path to the manifest within that repository. Defaults to `repos.yaml`. |+| Branch | Branch to read the manifest from. Leave blank for the default branch. |+| Sync schedule | How often to reconcile automatically. Choose a preset or enter a custom cron expression. Set to **Manual only** to disable scheduled syncs. |+| Prune removed repositories | Delete GitOps-managed repositories that are no longer in the manifest. Off by default. |++The manifest repository is cloned with the Git token from **Settings → Integrations**, so private repositories work without any extra credentials. If you have not configured a GitHub App or personal access token for the host, the sync reports a clear error.++<Warning>+Pruning permanently deletes a repository's indexed data (snippets and embeddings). It only affects repositories GitOps added, never ones you created in the dashboard, but treat the manifest as authoritative once pruning is on. Removing an entry and syncing will delete that library.+</Warning>++## When syncs happen++A reconcile runs in four situations:++- **On startup.** When the instance boots with GitOps enabled, it reconciles immediately. This is what makes disaster recovery a single step: bring up a fresh instance pointed at the manifest repo and the index rebuilds itself.+- **On a schedule.** The cron schedule you set acts as a steady fallback that keeps the instance in line with the manifest.+- **On push (webhook).** If the manifest repository is on a connected GitHub App, every push triggers an immediate sync. See [Webhooks](#webhooks) below.+- **On demand.** Click **Sync now** in the dashboard, or call the API, to reconcile right away.++Repeated syncs are cheap. Context7 remembers the last commit it processed and skips the work entirely when nothing has changed, and it only re-indexes a repository when its manifest entry actually differs.++## Webhooks++When the manifest repository is served by the [GitHub App](/enterprise/integrations/github), every push to its configured branch triggers an immediate sync, with no CI step required. Pushes to other repositories or other branches are ignored.++Webhook delivery requires the GitHub App, an instance reachable from GitHub, and the App subscribed to push events. See [GitHub Integration](/enterprise/integrations/github#webhooks) for setup, including what to do if you connected the App before push support existed. With a personal access token instead of the App, webhooks are unavailable; use the sync schedule or have CI call the reconcile endpoint.++## Disaster recovery++Because the repository list lives in Git, rebuilding an instance does not require restoring it from a backup. Stand up a fresh Context7 instance, configure your LLM and Git credentials, enable GitOps with the manifest repository URL, and start it. On boot it reads the manifest and re-indexes every listed repository. Your configuration is reproducible from code.++## API++The same operations are available over the REST API and require an admin [API key](/enterprise/api/authentication).++```+GET /api/gitops/status # current configuration and the last sync result+PUT /api/gitops/config # update the configuration+POST /api/gitops/reconcile # run a sync now+```++To propagate a manifest change from CI immediately (for example when you are not using a GitHub App), call the reconcile endpoint after merging:++```bash+curl -X POST http://localhost:3000/api/gitops/reconcile \+ -H "Authorization: Bearer <admin-api-key>"+```++The response reports what the sync did, including how many repositories were created, updated, left unchanged, pruned, and skipped.diff --git a/docs/enterprise/integrations/github.mdx b/docs/enterprise/integrations/github.mdxnew file mode 100644index 00000000..8f5582f2--- /dev/null+++ b/docs/enterprise/integrations/github.mdx@@ -0,0 +1,84 @@+---+title: "GitHub Integration"+sidebarTitle: "GitHub"+description: "Connect Context7 to GitHub with a GitHub App or a personal access token for private repository access and push webhooks"+---++Context7 needs access to your GitHub repositories to clone and index them. You can connect GitHub in two ways: a **GitHub App** (recommended) or a **personal access token**. The GitHub App additionally delivers push webhooks, which power push-triggered [GitOps](/enterprise/gitops) syncs.++Both are configured under **Settings → Integrations**.++## GitHub App++The GitHub App is the recommended option. It gives Context7 fine-grained access to only the repositories you select, rotates short-lived access tokens automatically, and delivers webhooks for push-triggered GitOps syncs.++Connecting the App is two steps: first create the App, then install it on your repositories.++<Steps>+ <Step title="Create the App">+ Go to **Settings → Integrations** and choose **Set up GitHub App**. Context7 generates a pre-filled App manifest and sends you to GitHub to create the App in one click. You are redirected back and Context7 stores everything it needs automatically: the App ID, private key, client ID and secret, and the webhook secret.+ </Step>+ <Step title="Install the App">+ After it is created, install the App on the account or organization that owns your repositories, and grant it access to the repositories you want to index (including your GitOps manifest repository, if you use GitOps).+ </Step>+</Steps>++Once both steps are done, the GitHub App card shows the connected App and its installation:++<Frame>+ +</Frame>++### Verify the App configuration++The setup flow configures everything below automatically, so a newly created App is ready to use. Use this section to confirm the App, or to fix an App you connected before GitOps existed (it will be missing the push event; see [Webhooks](#webhooks)). Open the App at `github.com/settings/apps`.++| Setting | Required value |+| ------- | -------------- |+| Repository permission: Contents | Read-only |+| Repository permission: Metadata | Read-only (mandatory) |+| Subscribed events | Push |+| Webhook | Active |+| Webhook URL | `https://<your-host>/api/github/webhook` |+| Webhook secret | Set |+| Callback URL | `https://<your-host>/api/github/callback` |+| Setup URL | `https://<your-host>/api/github/setup` |++Under **Permissions & events**, the repository permissions are granted and the **Push** event is subscribed:++<Frame>+ +</Frame>++Under **Webhook**, it is active and points at your instance with a secret configured:++<Frame>+ +</Frame>++## Personal access token++As a simpler alternative, add a GitHub personal access token under **Settings → Integrations**. Use a token with the `repo` scope for private repository access.++<Frame>+ +</Frame>++A personal access token can clone and index repositories, but it **cannot receive webhooks**. With a token only, push-triggered GitOps syncs are unavailable; use the GitOps sync schedule or trigger syncs from CI instead.++## GitHub Enterprise Server++To connect a GitHub Enterprise Server instance instead of github.com, set your GitHub Enterprise host under **Settings → Integrations**. The App or token then targets your server.++## Webhooks++When the GitHub App is connected, GitHub delivers `push` events to `https://<your-host>/api/github/webhook`. Context7 verifies each delivery's signature against the App's webhook secret and uses pushes to drive [GitOps](/enterprise/gitops) reconciliation: a push to a GitOps manifest repository triggers an immediate sync.++For delivery to work:++- Your instance must be **reachable from GitHub** at the webhook URL. An instance behind a firewall that GitHub cannot reach will not receive webhooks.+- The App must be **subscribed to push events** (new App setups are configured this way automatically).++<Warning>+GitHub Apps created before push support was added are not subscribed to any events, so they do not deliver webhooks. If you set up the App earlier, open it on GitHub and add the **push** event under its event subscriptions, confirm its webhook URL is `https://<your-host>/api/github/webhook`, or recreate the App from **Settings → Integrations**.+</Warning>diff --git a/docs/images/enterprise/gitops/gitops-settings.png b/docs/images/enterprise/gitops/gitops-settings.pngnew file mode 100644index 00000000..028fa7a9Binary files /dev/null and b/docs/images/enterprise/gitops/gitops-settings.png differdiff --git a/docs/images/enterprise/integrations/git-tokens.png b/docs/images/enterprise/integrations/git-tokens.pngnew file mode 100644index 00000000..6b2b3df1Binary files /dev/null and b/docs/images/enterprise/integrations/git-tokens.png differdiff --git a/docs/images/enterprise/integrations/github-app.png b/docs/images/enterprise/integrations/github-app.pngnew file mode 100644index 00000000..78cb27c6Binary files /dev/null and b/docs/images/enterprise/integrations/github-app.png differdiff --git a/docs/images/enterprise/integrations/github-permissions.png b/docs/images/enterprise/integrations/github-permissions.pngnew file mode 100644index 00000000..2058db5bBinary files /dev/null and b/docs/images/enterprise/integrations/github-permissions.png differdiff --git a/docs/images/enterprise/integrations/github-webhook.png b/docs/images/enterprise/integrations/github-webhook.pngnew file mode 100644index 00000000..8d1eeb64Binary files /dev/null and b/docs/images/enterprise/integrations/github-webhook.png differ