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.
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.
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
| strategy | What happens | Allowed when |
|---|---|---|
push | Every file — pages, config and images — goes into the repository in one commit on branch. The project switches to GitHub at once and builds that commit | The docs folder has no pages, and the project has pages in Syntext |
pull_request | The 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 requests | The repository isn't empty, and the project has pages in Syntext |
use_repo | Nothing 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 history | Always |
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
repoUrlhttps://github.com/acme/docs.strategypush, pull_request or use_repo.branchpush 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.docsPathdocs/ or the folder the repository already uses; / is the root.installationIdResponse — 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.
state becomes pr_closed and the project stays in Syntext.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
| Status | Code | When |
|---|---|---|
| 400 | validation_error | The body is invalid, e.g. a branch name GitHub wouldn't accept |
| 400 | invalid_repo_url | Not a GitHub repository URL |
| 400 | invalid_docs_path | docsPath isn't a plain folder inside the repository |
| 400 | unsupported_docs_path | Pages would go somewhere builds don't read — choose docs/ or the root |
| 403 | forbidden | You're not an admin or owner |
| 403 | repo_not_installed | The Syntext GitHub App isn't installed on the repository for this workspace. Install it, or add the repository to the installation |
| 404 | branch_not_found | The branch doesn't exist |
| 409 | already_linked | The project already builds from GitHub |
| 409 | repo_has_docs | push into a folder that already has pages — open a pull request or use the repository's pages |
| 409 | repo_empty | pull_request into an empty repository — push instead |
| 409 | nothing_to_push | push or pull_request with no pages in Syntext — use the repository's pages |
| 409 | branch_moved | Someone pushed to the branch while the pages were being moved. Try again |
| 409 | content_changed | Pages changed in Syntext while they were being moved. Try again |
| 413 | content_too_large | The project's files are over 200 MB |
| 413 | repo_too_large | The repository is too large to read from the root — choose its docs folder |
| 502 | github_error | GitHub refused a request |
| 503 | github_rate_limited | GitHub 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.