update github docs (vibe-kanban) (#1388)
* I have explored the codebase and confirmed that the GitHub integration now relies on the `gh` CLI instead of a Personal Access Token (PAT) configured in the settings. The setup process is "just-in-time", prompting the user to install or authenticate the CLI when they attempt to create a Pull Request. I have updated the documentation to reflect these changes: 1. **`docs/integrations/github-integration.mdx`**: Rewrote the guide to explain the CLI-based workflow, including automatic setup on macOS and manual setup instructions for other platforms, as well as troubleshooting steps. 2. **`docs/getting-started.mdx`**: Updated the installation steps to remove the instruction to "Connect to GitHub in Settings" and instead mention the `gh` CLI requirement. 3. **`docs/configuration-customisation/global-settings.mdx`**: Removed the "GitHub Integration" section (since it no longer exists in Global Settings) and replaced it with a "Git Configuration" section describing the "Branch Prefix" setting, which is present in the UI. I also verified that `docs/core-features/completing-a-task.mdx` remains accurate with the new workflow. No images were needed as the process is now primarily CLI-driven or standard dialog-based, and I removed the outdated screenshots from the documentation files. I ran `pnpm run check` to ensure no regressions were introduced, and it passed successfully. ### Summary of Changes | File | Change | | :--- | :--- | | `docs/integrations/github-integration.mdx` | Rewritten to document `gh` CLI usage and troubleshooting | | `docs/getting-started.mdx` | Removed outdated "Connect GitHub" step; added CLI info | | `docs/configuration-customisation/global-settings.mdx` | Removed GitHub section; added Git Branch Prefix section | * The "Troubleshooting" section has been removed from `docs/integrations/github-integration.mdx`. * I have performed a comprehensive search for "github" across the documentation and codebase. I found and updated a few more references to ensure consistency: 1. **`docs/core-features/completing-a-task.mdx`**: Updated the link text to "Set up GitHub CLI integration" instead of "Set up GitHub authentication". 2. **`docs/index.mdx`**: Updated the Settings card description to remove "GitHub integration" and replace it with "git settings". 3. **`docs/configuration-customisation/global-settings.mdx`**: Updated the alt text of the settings screenshot to remove the mention of "GitHub integration settings". I verified other references in `docs/core-features/creating-tasks.mdx`, `docs/core-features/monitoring-task-execution.mdx`, and `docs/supported-coding-agents.mdx` and confirmed they are either correct (referring to platform features like polling or agents like Copilot) or generic examples that don't need changing. The documentation now fully reflects the shift to the CLI-based GitHub integration workflow.
This commit is contained in:
Britannio Jarrett
committed by
GitHub
GitHub
parent
c4f4bf8318
commit
ddb21f969d
@@ -1,13 +1,13 @@
|
||||
---
|
||||
title: "Global Settings"
|
||||
description: "Configure application-wide settings including themes, agents, GitHub integration, and more"
|
||||
description: "Configure application-wide settings including themes, agents, and more"
|
||||
sidebarTitle: "Settings"
|
||||
---
|
||||
|
||||
You can configure application-wide settings via the **Settings** page. To access it, click the ⚙️ icon in the sidebar or select "Settings" from the top-right menu.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/vk-settings.png" alt="Vibe Kanban global settings page showing theme options, agent configuration, and GitHub integration settings" />
|
||||
<img src="/images/vk-settings.png" alt="Vibe Kanban global settings page showing theme options, agent configuration, and settings" />
|
||||
</Frame>
|
||||
|
||||
## Themes
|
||||
@@ -88,13 +88,13 @@ This works for both project-level and task worktree opening.
|
||||
Test your SSH connection first with `ssh user@host` to ensure it works without prompting for passwords.
|
||||
</Tip>
|
||||
|
||||
## GitHub Integration
|
||||
## Git Configuration
|
||||
|
||||
Link your GitHub account by providing a Personal Access Token (PAT) to enable:
|
||||
Configure git branch naming preferences.
|
||||
|
||||
- Automatic branch management
|
||||
- Pull request creation and tracking
|
||||
- Status synchronisation directly from Vibe Kanban
|
||||
### Branch Prefix
|
||||
|
||||
Set a prefix for auto-generated branch names (e.g., `vk` results in `vk/task-name`). Leave empty for no prefix.
|
||||
|
||||
## Notifications
|
||||
|
||||
|
||||
@@ -64,5 +64,5 @@ When your PR is merged on GitHub, your task automatically moves to **Done**.
|
||||
## Related Documentation
|
||||
|
||||
- [Resolving Rebase Conflicts](/core-features/resolving-rebase-conflicts) - Handle conflicts during rebasing
|
||||
- [GitHub Integration](/integrations/github-integration) - Set up GitHub authentication
|
||||
- [GitHub Integration](/integrations/github-integration) - Set up GitHub CLI integration
|
||||
- [Creating Projects](/core-features/creating-projects) - Configure base branches and project settings
|
||||
|
||||
@@ -46,7 +46,7 @@ Agents can still perform system-level actions, so review their work and keep bac
|
||||
</Step>
|
||||
|
||||
<Step title="Complete initial setup">
|
||||
Complete the setup dialogs to configure your coding agent and editor preferences. GitHub authentication is optional and can be configured later.
|
||||
Complete the setup dialogs to configure your coding agent and editor preferences. GitHub integration relies on the GitHub CLI and is configured when needed.
|
||||
</Step>
|
||||
|
||||
<Step title="Create your first project">
|
||||
@@ -57,8 +57,8 @@ Agents can still perform system-level actions, so review their work and keep bac
|
||||
Start tracking your work by [creating tasks](/core-features/creating-tasks) within your project.
|
||||
</Step>
|
||||
|
||||
<Step title="Optional: Configure GitHub integration">
|
||||
Connect to GitHub in [Settings](/configuration-customisation/global-settings) to enable branch management and pull request creation.
|
||||
<Step title="Optional: GitHub integration">
|
||||
Vibe Kanban uses the [GitHub CLI](https://cli.github.com/) for creating pull requests. Ensure `gh` is installed and authenticated on your system, or follow the setup prompts when creating your first pull request.
|
||||
</Step>
|
||||
|
||||
<Step title="Optional: Set up MCP integration">
|
||||
|
||||
@@ -37,6 +37,6 @@ Vibe Kanban is an **orchestration platform for AI coding agents** that helps dev
|
||||
</Card>
|
||||
|
||||
<Card title="Settings" icon="gear" href="/configuration-customisation/global-settings">
|
||||
Configure themes, default agents, GitHub integration, and more
|
||||
Configure themes, default agents, git settings, and more
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -3,33 +3,38 @@ title: "GitHub Integration"
|
||||
description: "Connect to GitHub to create pull requests and manage your workflow directly from Vibe Kanban"
|
||||
---
|
||||
|
||||
Connect your GitHub account to create pull requests and push changes directly from task attempts.
|
||||
Vibe Kanban integrates with GitHub to let you create pull requests directly from your task attempts. This integration relies on the [GitHub CLI (`gh`)](https://cli.github.com/) being installed and authenticated on your system.
|
||||
|
||||
## Connect Your GitHub Account
|
||||
## Setup
|
||||
|
||||
<Frame>
|
||||
<img src="/images/github-connect-settings.png" alt="Settings page with Connect GitHub Account button" />
|
||||
</Frame>
|
||||
There is no need to configure GitHub in the Vibe Kanban settings manually. The integration is designed to work out-of-the-box if you have the GitHub CLI installed.
|
||||
|
||||
Click **Connect GitHub Account** in General Settings to authenticate with GitHub using device flow authentication.
|
||||
### Automatic Setup
|
||||
When you attempt to create your first Pull Request, Vibe Kanban will check if the GitHub CLI is available. If it's not found or not authenticated, you will be guided through the setup process:
|
||||
|
||||
<Frame>
|
||||
<img src="/images/github-device-code.png" alt="GitHub device authentication dialog with verification code" />
|
||||
</Frame>
|
||||
1. **On macOS**: You will see a dialog offering to install the GitHub CLI via Homebrew automatically.
|
||||
2. **On Windows/Linux**: You will be provided with instructions to install the CLI manually.
|
||||
|
||||
The authentication process is simple:
|
||||
1. Click **Sign in with GitHub**
|
||||
2. Visit the provided GitHub URL in your browser
|
||||
3. Enter the device code shown in the dialog
|
||||
4. Authorize Vibe Kanban in your browser
|
||||
5. Return to complete the setup
|
||||
### Manual Setup
|
||||
You can also set up the integration manually in your terminal before using Vibe Kanban:
|
||||
|
||||
**Required Permissions**: Vibe Kanban needs access to your repositories (`repo`), basic profile info (`read:user`), and email address (`user:email`) for Git commits.
|
||||
1. **Install GitHub CLI**: Follow the [official installation instructions](https://github.com/cli/cli#installation) for your operating system.
|
||||
2. **Authenticate**: Run the following command in your terminal and follow the prompts:
|
||||
```bash
|
||||
gh auth login
|
||||
```
|
||||
Select **GitHub.com**, choose **HTTPS** or **SSH** as your preferred protocol, and complete the login via the web browser.
|
||||
|
||||
<Note>
|
||||
If you encounter permission issues when creating pull requests, you'll be prompted to provide a Personal Access Token as a fallback authentication method.
|
||||
</Note>
|
||||
## Creating a Pull Request
|
||||
|
||||
## Related Documentation
|
||||
Once the GitHub CLI is ready, you can create pull requests directly from a task:
|
||||
|
||||
- [Completing a Task](/core-features/completing-a-task) - Learn how to create pull requests and manage branches
|
||||
1. Open a task that has changes you want to merge.
|
||||
2. Click the **Create PR** button.
|
||||
3. A dialog will appear pre-filled with:
|
||||
* **Title**: Derived from the task title.
|
||||
* **Description**: Derived from the task description.
|
||||
* **Base Branch**: The target branch for your changes (defaults to the repository's default branch or the one specified in the attempt).
|
||||
4. Click **Create** to open the PR on GitHub.
|
||||
|
||||
If the operation is successful, the task status will update, and a link to the new Pull Request will be available.
|
||||
|
||||
Reference in New Issue
Block a user