Connecting the Mintlify GitHub App
Relevant source files
The following files were used as context for generating this wiki page:The Mintlify GitHub App is a crucial component for automating the documentation publishing process. It connects your GitHub repository directly to the Mintlify deployment service, enabling a seamless Continuous Integration and Continuous Deployment (CI/CD) workflow. When configured, any changes pushed to the default branch of your repository are automatically built and deployed to your live documentation site.
This integration eliminates the need for manual deployment steps, ensuring that your documentation stays in sync with your source files. The process is managed through the Mintlify dashboard, providing a central place for configuration and control. For a complete walkthrough, you can also refer to the Quickstart Guide.
Sources: README.md:22-24, README.md:10
Architecture Overview
The system consists of several key components that work together to facilitate both local development and automated production deployments. The docs.json file acts as the central configuration for the documentation site, defining its structure, navigation, and appearance. For local previews, the Mintlify CLI is used. For production, the GitHub App takes over.
Sources: README.md:13-24, docs.json
Key Components
| Component | Description | Source File(s) |
|---|---|---|
| Mintlify CLI | A command-line tool for local development. It allows you to run a local server and preview changes in real-time. | README.md:13-19 |
docs.json | The main configuration file for the documentation project. It defines navigation, theme, colors, and other settings. | docs.json, README.md:18 |
| Mintlify Dashboard | A web interface for managing your organization's settings, including the GitHub App integration. | README.md:22, docs.json:96-98 |
| GitHub App | The integration that connects your GitHub repository to Mintlify's deployment service for automated publishing. | README.md:22-24 |
| Content Files | Markdown (.md/.mdx) or OpenAPI JSON files (.json) that contain the documentation content, such as guides and API references. | api-reference/openapi.json |
Installation and Setup
Connecting the GitHub App is initiated from the Mintlify dashboard. This one-time setup authorizes Mintlify to access your repository and set up webhooks that trigger deployments.
Sources: README.md:22
Setup Flow
The following diagram illustrates the steps to install and authorize the GitHub App.
This diagram shows the user flow for installing the Mintlify GitHub App, starting from the Mintlify dashboard and proceeding through the GitHub authorization process.
Sources: README.md:22, docs.json:96-98
Deployment Workflows
The project supports two distinct workflows: local development for previewing changes and a production workflow for publishing the live site.
Local Development
For local development, the Mintlify CLI provides a command to run a hot-reloading server. This is ideal for drafting content and previewing structural changes before pushing them to the repository.
- Install the CLI globally:
npm i -g mint - Run the development server from the root of your project (where
docs.jsonis located):mint dev - Preview your site at
http://localhost:3000.
Sources: README.md:13-19, development.mdx
Production Deployment
Production deployment is fully automated by the Mintlify GitHub App. Once the app is installed and configured for your repository, the following sequence of events occurs whenever code is pushed to the default branch.
The following diagram shows the automated deployment sequence.
This sequence diagram illustrates how a git push to the default branch triggers the Mintlify GitHub App, leading to an automatic build and deployment of the documentation site.
Sources: README.md:22-24, docs.json, api-reference/openapi.json
Configuration
The primary configuration for the documentation site is handled by the docs.json file. While this file does not directly configure the GitHub App connection, it defines what is deployed. It includes navigation, branding, and links to external resources like the dashboard.
Dashboard Link Configuration
The link to the Mintlify dashboard, where the GitHub App is managed, can be configured in the navbar section of docs.json.
{
"navbar": {
"links": [
{
"label": "Support",
"href": "mailto:hi@mintlify.com"
}
],
"primary": {
"type": "button",
"label": "Dashboard",
"href": "https://dashboard.mintlify.com"
}
}
}
Sources: docs.json:92-102
Summary
Connecting the Mintlify GitHub App provides a powerful, automated CI/CD pipeline for your documentation. It bridges the development environment in your GitHub repository with the live, published documentation site. By listening for pushes to the default branch, the app ensures that your documentation is always up-to-date with minimal manual intervention, allowing developers and writers to focus on creating quality content.
Sources: README.md:22-24, quickstart.mdx