GitHub Issues Integration

GitHub Issues rides on the GitHub connection you already have. There is no second authorization: once the DevClocked GitHub App can read a repository, DevClocked can sync that repository's issues and match them to tracked work. The connection is read-only, so DevClocked never comments on, closes, or edits your issues.

What gets connected

• Your GitHub connection — the same DevClocked GitHub App installation that syncs your commits. Enabling GitHub Issues does not ask for new permissions.
• Issue sync — DevClocked pulls issues (number, title, state, assignee) from the repositories the App is installed on, into a read-only cache it can link work against.
• Evidence links — DevClocked matches issue references in commit messages and pull requests to the tracked work that contains them.

Pull requests are not synced as issues. Only repositories covered by your GitHub App installation are synced, so if issues are missing, check the installation's repository access first.

Enable GitHub Issues

1. Connect GitHub first. Open Settings > Integrations, find the GitHub card, and complete the App install if it is not already connected. See Connecting GitHub.
2. Find the GitHub Issues card and click Enable.
3. The card switches to Enabled straight away. There is no redirect to GitHub, because the existing connection is reused.

If the GitHub card is not connected, the Enable GitHub Issues button stays disabled and tells you to connect GitHub first. DevClocked runs a first sync automatically once enabled. After that, issues re-sync on a schedule (roughly hourly), and you can force a refresh at any time with Sync issues in the GitHub Issues dialog.

How issues link to your work

A GitHub issue is identified by its repository and number, written owner/repo#142. DevClocked links issues to tracked work using that reference:

• Commit messages — a message such as owner/repo#142 fix token refresh links the issue to that commit. A bare #142 also links, resolved against the repository the commit belongs to.
• Pull requests — a reference in the pull request's head branch, or commits already linked to the issue, adds pull-request evidence when the issue is viewed.
• Issue URLs — a GitHub issue URL such as https://github.com/owner/repo/issues/142 resolves to the same issue as owner/repo#142.

File names and file paths are not scanned. If a reference appears only in a file name or path, DevClocked will not create an automatic link. A direct attachment to the top-level session can be added manually from the session's issue picker.

Issue linking runs in the background every 30 minutes and checks recent tracked work from the previous 14 days. An already-synced issue can therefore take up to 30 minutes to appear automatically. Cross-repository matches are kept as suggestions until you explicitly confirm them.

Managing the connection

• Sync issues — force an immediate re-sync of your GitHub issues.
• Disconnect — stop syncing issues. Your GitHub connection, commits, and sessions are untouched, and you can re-enable at any time.

Troubleshooting

The Enable button is disabled.

GitHub itself is not connected, or the App connection is no longer active. Fix it on the GitHub card, then come back to GitHub Issues.

Issues from one repository are missing.

The DevClocked GitHub App is probably not installed on the account or org that owns that repository, or the repository is not in the App's selected list. Adjust the installation in GitHub, then run Sync issues.

Issues are not linking to my work.

Linking relies on the reference appearing in a commit message, commit branch, or pull-request branch. Make sure the relevant repositories are tracked, and do not rely on the reference appearing only in a file name or path.