Connect your code repositories
How to link a GitHub repository to a Penling initiative so you can surface branch, pull-request, and build status alongside your work.
Connecting a GitHub repository to an initiative lets Penling surface real code activity — tracked branch, open pull requests, and build status — alongside your focus areas and actions. This guide walks you through connecting GitHub to your workspace and linking a repository to a specific initiative.
Before you start
You'll need:
- A Penling workspace (Admin or Member role)
- A GitHub account with access to the repository you want to connect
- Owner or write permissions on the GitHub repository (needed to install the Penling GitHub App)
Step 1: Open the initiative's Settings page
Navigate to the initiative you want to connect a repository to, then click Settings in the left sidebar. You'll see a Repositories section below the Structure section.
Step 2: Connect your GitHub account
If you haven't connected GitHub yet, you'll see a Connect GitHub button. Click it.
Penling will redirect you to GitHub to install the Penling GitHub App. On the GitHub authorisation screen:
- Choose whether to grant access to all repositories or only selected repositories. Selecting specific repositories is recommended — you can always grant access to more later.
- Click Install & Authorise.
GitHub will redirect you back to the initiative's Settings page. You should see a confirmation that the GitHub account is now connected.
Step 3: Link a repository to the initiative
Once GitHub is connected, a repository picker appears in the Repositories section.
- Click the Select a repository… dropdown and choose the repository you want to link.
- Click Connect.
The repository now appears in the list. Penling will show the tracked branch — the branch this initiative builds against. This is the repository's default branch by default.
You can connect multiple repositories to a single initiative if the work spans more than one codebase (for example, a separate API repo and a frontend repo).
Step 4: Verify the connection
The connected repository row shows:
- Repository name (e.g.
your-org/my-app) - Tracked branch — the branch Penling monitors for commits and pull requests
- A Disconnect button if you need to remove the link later
Penling will now surface pull-request and build status on actions that reference this repository.
Add more repositories later
If you can't see a repository in the picker, it may not be accessible to the Penling GitHub App yet. Click Manage on GitHub to open the GitHub App settings and grant access to additional repositories. Return to the Settings page and refresh — the new repository will appear in the picker.
Disconnect a repository
To remove a repository link, click Disconnect next to the repository in the list. This disconnects the link in Penling only — it does not affect the GitHub repository itself. You can reconnect any time.
Troubleshooting
The Connect GitHub button keeps redirecting me — Make sure your browser allows pop-ups or redirects from Penling. If you land on an error page on GitHub, check that your GitHub account has permission to install Apps on the target organisation.
A repository I need isn't in the dropdown — Click Manage on GitHub and check which repositories the Penling App has access to. Grant access to the missing repository, then return to Penling.
I disconnected a repository by mistake — Use the same Select a repository picker to reconnect it. No data is lost by disconnecting.