GitHub Integration

RankAscend uses a GitHub App to publish content directly to your repository. Once connected, every generated article becomes a Markdown or MDX file committed to your configured branch, either as a direct push or a pull request ready for review.

Connecting GitHub

Navigate to Settings → Integrations → GitHub and click Connect Repository.

RankAscend redirects you to GitHub to install the GitHub App and authorize access to the repositories you choose. After authorization, GitHub redirects back and RankAscend automatically retrieves your installation ID.

RankAscend uses a GitHub App with an installation token, not a personal access token. This means access is scoped to the specific repositories you select during installation, and tokens rotate automatically every hour.

Once authorized, select the repository you want to publish to from the dropdown. RankAscend lists all repositories the app has access to.

Repository configuration

After connecting, configure how RankAscend writes to your repo under Settings → Integrations → GitHub:

Name
Branch
Type
string
Description
The branch RankAscend commits to. Defaults to your repo's default branch (usually main). For pull request mode, the base branch that feature branches are opened against.
Name
File format
Type
"md" | "mdx"
Description
Whether generated files use the .md or .mdx extension. Use .mdx if your framework processes MDX components; otherwise .md is fine.
Name
Publish mode
Type
"direct_push" | "pr"
Description
Controls how content lands in your repo. See Publish modes below.
Name
Content paths
Type
object
Description
Per-content-type directory where files are written. Defaults: blog articles → /blog, comparisons → /comparisons, use-cases → /use-cases, listicles → /listicles. Override any of these to match your project structure.

Publish modes

Direct push

RankAscend commits the file directly to your configured branch with a single API call. Your CI/CD pipeline picks it up immediately.

feat(content): publish "10 Best Practices for Next.js SEO" [RankAscend]

Use this when you trust auto-approved content and want zero friction.

Pull request

RankAscend creates a feature branch, commits the file, and opens a pull request against your base branch.

The PR is named after the article slug and includes a metadata table:

Auto-published by **RankAscend**

| Field   | Value                               |
|---------|-------------------------------------|
| Keyword | next-js-seo-best-practices          |
| Type    | blog                                |
| Words   | 1,847                               |
| Schema  | Article                             |

Use this when you want a human or CI review step before content goes live. Branch names follow the pattern publish/{slug}-{timestamp}.

File format

Every file RankAscend commits starts with YAML frontmatter containing all SEO metadata, followed by the article body in Markdown:

Example published file

---
title: "10 Best Practices for Next.js SEO"
description: "Learn how to optimize your Next.js app for search engines with these proven techniques."
date: "2025-06-22"
slug: "next-js-seo-best-practices"
content_type: blog
schema_type: Article
seo_platform_id: clx7f2k0p0001abc123
word_count: 1847
updated_at: "2025-06-22"
schema_json: '{"@context":"https://schema.org","@type":"Article",...}'
---

# 10 Best Practices for Next.js SEO

...

The schema_json field contains valid JSON-LD markup. Most frameworks expose this via a layout or <Head> component, RankAscend embeds it in the frontmatter so your build pipeline can inject it without a plugin.

RankAscend never modifies files it didn't create. If a file already exists at the target path, it updates only that file using the existing SHA, preserving any manual edits to the frontmatter.

Error handling and retry

Failed publish jobs are visible in Publish Log. Common failure reasons:

Error	Cause
`GitHub integration is not fully configured`	Repo URL or installation ID is missing, reconnect GitHub.
`Cannot parse GitHub repo URL`	The stored repo URL is malformed, remove and reconnect.
`GitHub auth failed`	The installation token could not be generated, check that the GitHub App is still installed on the repo.

RankAscend automatically retries failed jobs every 30 minutes. If a job fails three times, it stays in failed state until you manually reschedule it from the Publish Log.

Disconnecting GitHub

Go to Settings → Integrations → GitHub → Remove Repo. This removes the stored credentials from RankAscend. It does not uninstall the GitHub App from your account, do that from GitHub App Settings if needed.