/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Connect GitHub

Connect GitHub

Move a project written in Syntext to a GitHub repository: push its pages, open a pull request, or use the repository's pages.

POST/v1/projects/{projectId}/source/github/connectTry it
Session token

Link a project written in Syntext to a GitHub repository, so the repository becomes where its pages live. Only one place holds the pages at a time, and the move carries them. Run Preview GitHub Link first to see which strategies are possible.

Note

Requires the admin or owner role and a session JWT. The Syntext GitHub App must be installed on the repository for the project's workspace. Also works on a project published with stx deploy, which has no pages in Syntext: use use_repo.

Strategies

strategyWhat happensAllowed when
pushEvery file — pages, config and images — goes into the repository in one commit on branch. The project switches to GitHub at once and builds that commitThe docs folder has no pages, and the project has pages in Syntext
pull_requestThe files go in one commit on a new branch, syntext/move-from-syntext-<date>, and a pull request into branch is opened. The project stays in Syntext until it's merged — see Pending pull requestsThe repository isn't empty, and the project has pages in Syntext
use_repoNothing is written. The repository's pages become the source and the site builds from its branch head. The pages written in Syntext stay in its historyAlways

Pages go under the docs folder, images under public/, and syntext.json at the repository root. Your project's brand settings are written into syntext.json. Moving pages needs the docs folder to be docs/ or the root, since builds read pages from one of those.

Request Body

NameDescription
repoUrl:stringbodyRequired
The repository, e.g. https://github.com/acme/docs.
strategy:stringbodyRequired
push, pull_request or use_repo.
branch:stringbody
For push and use_repo, the branch the site builds from; for pull_request, the branch the pull request merges into. Defaults to the repository's default branch.
docsPath:stringbody
The docs folder. Omit it for docs/ or the folder the repository already uses; / is the root.
installationId:integerbody
The GitHub App installation to use. Found among the workspace's installations when omitted.

Response — 200 OK

push and use_repo finish at once:

•
build — the build of the new source, when one started.
•
warnings — present when something needs a look: hosted_changes_not_moved when pages were saved in Syntext after the move started (they're kept in Syntext's history), or a webhook that couldn't be set up.

Response — 202 Accepted

pull_request waits for the merge:

Pending pull requests

While the pull request is open, the project's githubSync.state is pending_merge. The editor keeps saving to Syntext and the site keeps publishing from Syntext.

•
Merged — the project switches to GitHub and builds the merge commit. GitHub's merge webhook does it, and so does the next Get GitHub Link if the webhook was missed.
•
Closed without merging — state becomes pr_closed and the project stays in Syntext.
•
Connect again with the same repository, branch and strategy — the latest Syntext pages are committed to the same pull request branch.
•
Cancel — Disconnect GitHub cancels the link. The pull request is left open on GitHub; close it there.

A move interrupted part-way (state: "failed" or "pushing") resumes when you connect again with the same repository, branch and strategy: files already sent aren't sent again.

Error Responses

StatusCodeWhen
400validation_errorThe body is invalid, e.g. a branch name GitHub wouldn't accept
400invalid_repo_urlNot a GitHub repository URL
400invalid_docs_pathdocsPath isn't a plain folder inside the repository
400unsupported_docs_pathPages would go somewhere builds don't read — choose docs/ or the root
403forbiddenYou're not an admin or owner
403repo_not_installedThe Syntext GitHub App isn't installed on the repository for this workspace. Install it, or add the repository to the installation
404branch_not_foundThe branch doesn't exist
409already_linkedThe project already builds from GitHub
409repo_has_docspush into a folder that already has pages — open a pull request or use the repository's pages
409repo_emptypull_request into an empty repository — push instead
409nothing_to_pushpush or pull_request with no pages in Syntext — use the repository's pages
409branch_movedSomeone pushed to the branch while the pages were being moved. Try again
409content_changedPages changed in Syntext while they were being moved. Try again
413content_too_largeThe project's files are over 200 MB
413repo_too_largeThe repository is too large to read from the root — choose its docs folder
502github_errorGitHub refused a request
503github_rate_limitedGitHub asked Syntext to slow down. details.retryAfterSeconds says when to try again; files already sent are kept

The strategy errors (repo_has_docs, repo_empty, nothing_to_push, unsupported_docs_path, content_too_large) are the ones Preview reports in strategies.

To set a repository on a project that has pages in Syntext, use this endpoint: Update Project refuses it with 409 use_connect_flow.

Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/connect \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{ "repoUrl": "https://github.com/acme/docs", "strategy": "push" }'
Responseapplication/json
200OK
{
"data": {
"contentSource": "github",
"strategy": "push",
"repoUrl": "https://github.com/acme/docs",
"branch": "main",
"docsPath": "docs",
"commitSha": "9d4e1b7c3a5f8e2d6b0c4a9f1e7d3b5c8a2f6e0d",
"build": { "id": "b7d2e9a4-1c3f-4b8e-9a6d-2f5c8e1b4a70", "status": "queued" }
}
}
Responseapplication/json
202Accepted
{
"data": {
"contentSource": "hosted",
"strategy": "pull_request",
"repoUrl": "https://github.com/acme/docs",
"branch": "main",
"docsPath": "docs",
"commitSha": "4c8e2a6f0b1d3e5c7a9f1b3d5e7c9a1b3d5f7e9c",
"pullRequest": { "number": 42, "url": "https://github.com/acme/docs/pull/42" },
"pendingMerge": true
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext