GitHub Integration

The Git tab of a project shows the issues and the GitHub Actions workflow runs of its repository, in the Issues and Actions sub-tabs. For Changes and History, see Git Changes.

You can read, search, create, comment on, close and reopen issues. You can watch workflow runs, read job logs, re-run jobs and cancel runs. You can send an issue or a failed run to your AI tool.

The sub-tabs are available for all projects.

Connect GitHub

When you are not connected, the tab shows Connect GitHub. You can connect in two ways:

Method	Use it when
GitHub App	You do not use the GitHub CLI, or you want live Actions updates and notifications.
GitHub CLI	You are logged in to gh and you do not want to install the GitHub App.

DevWorkspace Pro uses one GitHub account for all projects.

Below the GitHub CLI button, the tab shows The GitHub CLI login gets no live Actions updates or run notifications. Only the GitHub App sign-in gets them.

On Linux without a system keyring, the tab also shows This computer has no system keyring. Your sign-in is kept with basic protection only. before you connect. See Where the token is stored.

Connect with the GitHub App

DevWorkspace Pro uses the devworkspace-pro GitHub App and the GitHub device flow.

1. Click Connect GitHub. DevWorkspace Pro gets a code from GitHub, copies it to the clipboard and opens the GitHub device page in your browser.
2. Paste the code on the GitHub page and approve access.
3. The tab updates when sign-in is complete.

While DevWorkspace Pro waits, the tab shows the code and the time until it expires.

• To copy the code again, click the copy icon.
• To open the GitHub page again, click Open again. This also copies the code again.
• To stop, click Cancel.

The code expires after 15 minutes. Then the tab shows The code expired. Click Get a new code.

The GitHub App can only see the repositories that you give it access to. See No access to a repository.

Connect with the GitHub CLI

If the GitHub CLI (gh) is installed and logged in, the tab shows Use your GitHub CLI login as @user. Click it. DevWorkspace Pro uses the gh token and remembers your choice.

The gh login must have the repo scope. If it does not, the tab shows the command to fix it:

gh auth refresh -s repo

If gh is not installed or not logged in, the button does not show. Run gh auth login, or connect with the GitHub App.

Organisations with SAML SSO or OAuth app restrictions

An organisation can block the GitHub CLI. Then the repository shows Your GitHub CLI login is blocked by the organisation organization. Authorize gh for the organisation on GitHub, or connect with the GitHub App.

No live Actions updates with the GitHub CLI

Live run updates and Actions notifications need the GitHub App. With the GitHub CLI, the run list updates when you open the tab or click refresh. The account menu also tells you this when you use the GitHub CLI. See Notifications.

Where the token is stored

The GitHub token stays in the main process of the app. The pages of the app never get it.

• GitHub App: DevWorkspace Pro encrypts the token with the system keychain (Electron safeStorage) and keeps it in a file on your computer. It refreshes the token when it expires.
• GitHub CLI: DevWorkspace Pro does not keep a copy of the token. It gets the token from gh each time.

On Linux without a system keyring (Secret Service), DevWorkspace Pro keeps the sign-in on disk with basic protection only: the file is encrypted, but not with a key from the system keyring. You stay signed in after a restart. Before you connect, the sign-in screen shows This computer has no system keyring. Your sign-in is kept with basic protection only. After you connect, the account menu shows No system keyring is available, so the sign-in is kept with basic protection only.

Account menu

The avatar at the right end of the tab toolbar opens the account menu. The same menu is in Settings → Preferences → Monitoring, in the GitHub account row.

The menu shows:

• Your avatar, name and @login.
• The sign-in method: GitHub App or GitHub CLI.
• Manage access on GitHub: opens the GitHub page where you select the repositories of the GitHub App, or the authorised application page for the GitHub CLI.
• Sign out.
• Reconnect, when the sign-in expired.

Sign out removes the stored token from this computer and clears the GitHub data in the app. It does not revoke the token on GitHub. To revoke access, click Manage access on GitHub and remove the app there. With the GitHub CLI, sign out does not log out gh.

Expired sign-in

If GitHub refuses the token and DevWorkspace Pro cannot refresh it, the tab shows GitHub sign-in expired. You see saved data. The data that the tab loaded before stays on the screen.

Click Reconnect. With the GitHub App, the new code shows below the banner. With the GitHub CLI, DevWorkspace Pro reads the gh token again.

The Repository

DevWorkspace Pro finds the repository of the project in this order:

1. The GitHub URL on the Overview tab (Project Information card), if it is set.
2. The origin Git remote of the project folder.
3. The first other Git remote that points to GitHub.

The toolbar shows the repository and its source: Project setting or From remote. To set or change the URL, click the pencil icon in the toolbar. You can also click Edit GitHub URL on the project overview. See DDEV Projects.

These URL forms are valid:

Form	Example
HTTPS	https://github.com/owner/repo or https://github.com/owner/repo.git
No scheme	github.com/owner/repo
SSH	[email protected]:owner/repo.git
SSH URL	ssh://[email protected]/owner/repo.git

DevWorkspace Pro uses only the owner and repository name. It ignores other parts of the path. Only github.com is supported.

State	The tab shows	Fix
No GitHub remote and no URL	Add a GitHub remote	Add an origin remote, or click Set repository manually. After you change the remotes, click Check again.
The URL in the project settings is not valid	The repository URL is not valid	Click Edit repository URL and enter a valid URL.

No access to a repository

If GitHub returns "not found" or "forbidden" for the repository, the tab shows No access to this repository with the reason:

• GitHub App: DevWorkspace Pro has no access to owner/repo. Click Give access on GitHub, select the repository on GitHub, then click Try again.
• GitHub CLI: Your GitHub CLI login has no access to owner/repo, or the organisation message above.

Toolbar

Item	What it does
Issues / Actions	Switch the sub-tab. Issues shows the number of open issues.
Repository	The owner/repo name, its source, an icon to open it on GitHub, and a pencil icon to change it.
CI status	The status of the latest loaded workflow run on the checked-out branch, for example Passed or Failed. The dot pulses while the run is in progress. Click it to open Actions.
Updated X ago	The time of the last load of the sub-tab. It shows Updating… during a load.
Refresh icon	Loads the issues or runs again. It also loads the open issue or the selected run again.
Avatar	Opens the account menu.

Offline

If GitHub cannot be reached, the tab shows You are offline. Data from X ago. The data that the tab loaded before stays on the screen. Click refresh when you are online again.

Rate limit

GitHub limits the number of API requests each hour. When few requests are left, Actions shows N API requests left until time. When the limit is reached, the tab shows GitHub rate limit reached. On Issues, it also shows the time when you can try again.

Issues

The Issues sub-tab shows a list of issues on the left and the selected issue on the right. Pull requests do not show. The most recently updated issues are at the top.

Filters and search

Filter	Issues
Open	All open issues
Closed	All closed issues
Assigned to me	Open issues that are assigned to you
Mentioned	Open issues that mention you

Open and Closed show the number of issues.

You can also filter by Label and by Assignee. To remove the search text and the label and assignee filters, click the Clear filters icon.

Type in Search issues to search. The list updates when you stop typing, or when you press Enter. You can use GitHub search syntax, for example author:octocat or no:assignee. Press Esc to clear the search.

The list loads some issues at a time. Click Load more at the end of the list. GitHub search returns a maximum of 1,000 results.

Keyboard shortcuts

Click the list, or press Esc in an empty search field, to give the list the focus.

Key	Action
j or ↓	Select the next issue. At the end of the list, load more issues.
k or ↑	Select the previous issue
Enter	Open the selected issue
Esc	Go back to the list. Press again to clear the selection.
o	Open the selected issue on GitHub
/	Go to the search field

Issue details

The issue panel shows the title, the state (Open, Closed or Not planned), the author, the assignees, the labels, the description and all comments. Markdown shows as formatted text. Links open in your browser.

The icons at the top of the panel:

Icon or button	Action
Send to Focus Pad	Adds the issue as a task in Focus Pad.
Send to AI	Sends the issue to your AI tool. See Send an Issue to AI.
Open on GitHub	Opens the issue in your browser.
Close	Select Close as completed or Close as not planned.
Reopen	Shows on a closed issue. Opens it again.

When you complete a Focus Pad task that came from an issue, Focus Pad asks if you want to close the issue on GitHub.

Comment on an Issue

Type in the comment field at the bottom of the panel. Markdown is supported. Click Comment, or press ⌘+Enter (Ctrl+Enter on Windows and Linux).

If GitHub does not accept the comment, the panel shows The comment was not sent and keeps your text. Click Try again.

Send an Issue to AI

1. Open the issue and click Send to AI. The dialog shows the prompt: the repository, the issue number, title, link and description, and all comments with their author and date.
2. Optional: type more text in Additional details. DevWorkspace Pro adds it to the end of the prompt.
3. Click Send, or press ⌘+Enter (Ctrl+Enter on Windows and Linux).

Your AI CLI tool starts in a terminal in DevWorkspace Pro, in the project root folder. See AI Sessions.

Create an Issue

1. Click New issue.
2. Type a Title. The title can have a maximum of 256 characters.
3. Optional: type a Description. Markdown is supported.
4. Optional: select Labels.
5. Click Create issue, or press ⌘+Enter (Ctrl+Enter on Windows and Linux).

The new issue shows at the top of the Open list.

What the tab keeps

DevWorkspace Pro keeps this data for each repository, also when you switch projects or tabs:

• The sub-tab of the Git tab. The app keeps it after a restart.
• The search text, the filters and the selected issue.
• Comment drafts, for each issue.
• On Actions: the filters and the selected run.

All items except the sub-tab are kept until you quit the app.

GitHub Actions

The Actions sub-tab shows the workflow runs on the left and the selected run on the right.

Filters

Filter	Options
Branch	The checked-out branch, marked (current), is the default. If that branch has no runs, the list shows All branches and the note "No runs on branch. Showing all branches." When you check out a different branch, the default changes to it when you open or refresh Actions. Select All branches or another branch from the loaded runs.
Workflow	All workflows, or one workflow of the repository
Status	All statuses, Running, Queued, Passed, Failed, Cancelled, Completed

If no runs match, click Show all runs to clear the filters.

Each row shows the run title, its status, the workflow, the branch, the duration, the user who started it and the time.

Keyboard shortcuts

Click the run list to give it the focus.

Key	Action
j or ↓	Select the next run
k or ↑	Select the previous run
Home / End	Select the first or the last run
Enter	Move the focus to the run details. If no run is selected, select the first run.
Esc	Clear the selection

Run details

The run panel shows the status, the workflow name and run number, the attempt number, the Branch, the Commit, Triggered by (user and event), Started, Duration and a Jobs summary.

While the run is not complete, the run and its jobs update automatically.

Button	Shows when	Action
Re-run failed jobs	The run is complete and has failed or cancelled jobs	GitHub starts the failed jobs again.
Re-run all jobs	The run is complete	GitHub starts all jobs again.
Cancel run	The run is not complete	Asks Cancel this run? Click Cancel run to stop all jobs that are running or queued, or Keep running.
Send failure to AI	A job failed	Sends the failure to your AI tool.
Copy failure for AI (icon)	A job failed	Copies the same prompt to the clipboard.
Open on GitHub (icon)	Always	Opens the run in your browser.

Send failure to AI and Copy failure for AI make a prompt with the repository, the workflow, the run number and attempt, the branch, the commit, the run link, the failed job, the failed step and the end of the log of the failed step. Send failure to AI opens the Send to AI dialog. See Send an Issue to AI for the steps.

Jobs and logs

The Jobs list shows each job with its status and duration. Click a job to show its steps and its log. Click a step to go to that step in the log.

When you open a run, the log of the first failed job shows. The failed step opens and the log scrolls to the first error.

The log shows one section for each step. Click a section to open or close it. Errors and warnings have a color.

Control	Action
Search log	Finds text in the log. Press Enter for the next match and Shift+Enter for the previous match. Press Esc to clear.
Wrap icon	Wraps long lines. The app remembers your choice.
Copy icon	Copies the log.
Reload icon	Loads the log again.

GitHub gives the log only when the job is complete. While a job runs, the log area shows This job is running. Click Watch on GitHub to see the live log.

For a long log, DevWorkspace Pro shows only the end of the log. To see the full log, open the job on GitHub.

GitHub keeps logs for a limited time. When a log has expired, the log area shows These logs have expired and a link to the job on GitHub.

When you open a job that you opened some time before, DevWorkspace Pro can load its log again.

Notifications

DevWorkspace Pro sends a notification when a workflow run completes. Set the level in Settings → Preferences → Monitoring → GitHub Actions Notifications:

Level	Notifications
all	Each run that completes. This is the default.
failures	Only runs that fail.
off	No notifications.

DevWorkspace Pro sends a notification for a run only when both are true:

• The repository is the repository of one of your projects in DevWorkspace Pro.
• You started the run, or the run is on the branch that is checked out in that project.

A failed run has the title Workflow failed — project. Click the notification to open the project, Git › Actions and the run.

Notifications and live updates of the run list need all of these:

• A GitHub App sign-in. The GitHub CLI sign-in does not get them.
• An active licence.
• Enable GitHub Actions turned on in Settings → Preferences → Monitoring. It is on by default. When it is off, the run list updates only when you open the tab or click refresh.

Troubleshooting

Problem	Fix
No access to this repository	With the GitHub App, click Give access on GitHub and select the repository. With the GitHub CLI, make sure your gh account can open the repository, and authorize gh for the organisation if it uses SAML SSO.
Use your GitHub CLI login does not show	Run gh auth status. Log in with gh auth login. Add the scope with gh auth refresh -s repo.
Add a GitHub remote	Add an origin remote that points to GitHub, or set the URL in the project settings.
The app says the sign-in has basic protection only (Linux)	Install and unlock a Secret Service keyring, for example GNOME Keyring or KWallet, then sign out and connect again.
No issues in a repository	Make sure issues are enabled in the repository settings on GitHub.
No Actions notifications	Connect with the GitHub App. Check the level in Preferences → Monitoring. On macOS, allow notifications for DevWorkspace Pro in System Settings → Notifications. If you gave the GitHub App access after you connected, sign out and connect again.