GitHub Integration

Connect your GitHub repositories to Projectyl to create branches directly from tasks and automatically track pull requests through their lifecycle.

Setup

1. Go to Settings → Integrations
2. Click Connect GitHub
3. You'll be redirected to GitHub to authorize the Projectyl GitHub App
4. Select the organization or personal account you want to connect
5. Choose which repositories to grant access to (you can change this later)
6. Confirm the installation

Once connected, the integration appears in your Settings with an Active status.

Connecting Multiple Accounts

You can connect multiple GitHub organizations or personal accounts to a single workspace. If you have several GitHub App installations, a picker dialog will appear after authorization so you can choose which account to connect.

To add another account after initial setup:

1. Go to Settings → Integrations
2. Click Install on another account in the connection picker, or Add GitHub Account
3. Follow the GitHub authorization flow and select the new account

Managing Access

To change which repositories Projectyl can access after installation:

1. Go to Settings → Integrations
2. Click Manage next to your GitHub connection
3. This opens GitHub's installation settings for that specific account where you can add or remove repositories

Suspended Connections

If your GitHub connection becomes suspended (e.g., due to billing or admin action on GitHub), click Unsuspend in Settings → Integrations. This will take you directly to the GitHub installation settings page where you can resolve the issue.

Removing

To disconnect GitHub entirely, click Remove next to the connection. This removes the link between Projectyl and the GitHub installation but does not delete any branches or pull requests on GitHub.

Setting a Preferred Repository

You can set a default repository for each project so developers don't have to select one every time they create a branch.

1. Open your project's Settings
2. Under Preferred Repository, select a repository from the dropdown
3. This repository will be pre-selected in the branch creation dialog

Creating Branches from Tasks

1. Open a task's detail view
2. Scroll to the Development section
3. Click Create Branch
4. In the dialog:
   • Repository — Select a repo (pre-filled if a preferred repository is set)
   • Source Branch — The branch to create from (defaults to the repo's development branch or default branch)
   • Branch Name — Auto-generated from the task key and title (e.g., feat/PROJ-42-user-login). You can edit this before creating.
5. Click Create

The branch is created on GitHub immediately, and a Branched indicator appears in the Development section.

Automatic PR Tracking

When a pull request is opened on GitHub, Projectyl automatically detects task references and links the PR to the corresponding tasks. No manual action is required.

How Task Keys Are Matched

Projectyl looks for task keys (e.g., PROJ-42) in three places:

• Branch name — fix/PROJ-42-login-bug
• PR title — feat: add login validation (PROJ-42)
• PR body — Fixes PROJ-42 and PROJ-43

A single PR can reference multiple tasks, and each will be linked automatically.

Development Lifecycle

Each linked branch/PR shows a three-stage progress indicator in the task's Development section:

If a PR is closed without merging, the stage reverts to Branched.

Dismissing Links

To remove a development link from a task, click the dismiss button on the link. This only removes the link in Projectyl — it does not delete the branch or PR on GitHub.

Permissions