FAQ

You work on an organization and want to use Pulldog with Github but you receive a 403 error when trying to add your repository. Github enable third party applications (as Pulldog) to access resources of your organization using 3 different authentication methods:

• Using Github app
• Using Github OAuth app
• Using Personal access token (Classic or Fine grained)

Pulldog is a Github OAuth app meaning you login through Pulldog and the application can act on your behalf to retrieve pull requests, pipelines status, ...

However in case you work on an Organization there is a top-layer of control that your IT department can configure. In an organization, OAuth app access restrictions are enabled by default. Meaning Github OAuth app cannot access organization resources without IT department explicitly authorize this application (this is true for Github OAuth app but also for Github app).

Organization owners (most likely IT department) can disable OAuth app access restrictions at any time as well as a authorizing specific Github app to access organization resources following these links:

• https://github.com/organizations/<ORG_NAME>/settings/oauth_application_policy

  

So you can ask your IT department to authorize Pulldog Github OAuth app to get ride of these 403 error if you are on this scenario.

Pulldog also support login through a P.A.T (Personal access token). Github enable 2 types of PAT:

• Classic token: By default, personal access tokens (classic) can access content owned by your organization via the GitHub API or Git over HTTPS. This includes both public and private resources such as repositories.
  If you choose to login using P.A.T you must check at least these scopes during your token creation process:

  • repo:status
  • public_repo
  • workflow
  • read:org
  • write:org
  • read:user
  • user:email
  • write:discussion

• Fine grained token: By default, fine-grained personal access tokens cannot access content owned by your organization via the Public API or Git. This includes both public and private resources such as repositories.
  If you choose to login using P.A.T you must check at least these scopes during your token creation process:

  • Actions (Read & write)
  • Administration (Read only)
  • Contents (Read & write)
  • Pull requests (Read & write)
  • Discussions (Read only)
  • Commit statuses (Read only)
  • Email addresses (Read only)

  

  

  Keep in mind that Organization owner can disable P.A.T access at any time:"Organization owners can control access to resources by applying policies to personal access tokens"

TLDR; Here is a table to sum-up everything:

In general we advice you to sign-in using Github OAuth app as scopes may evolve with Pulldog updates & new features, that will be automatically handled with Github OAuth app which will not be the case with a P.A.T and you will need to create a new one. If you need to use P.A.T we advise you to choose a "Classic token" as it may be pre-approved by default.

	Personal		Organization
	Github OAuth app			Need your IT department approvalhttps://github.com/organizations/<ORG_NAME>/settings/oauth_application_policy
	Github app			Need your IT department approvalhttps://github.com/organizations/<ORG_NAME>/settings/installations
	Classic	Fine-Grained	Classic	Fine-Grained
Personal Access Token (P.A.T)			* Only if your organisation haven't explicitly check: « Restrict access via personal access tokens (classic) » https://github.com/organizations/<ORG_NAME>/settings/personal-access-tokens?tab=classic	Need your IT department approval Check « Allow access via fine-grained personal access tokens » https://github.com/organizations/<ORG_NAME>/settings/personal-access-tokens Once you’ve created your token they need to approve the token https://github.com/organizations/<ORG_NAME>/settings/personal-access-token-requests

If you sign-in with a personal access token (P.A.T) be sure to have checked all the required scopes in order for your P.A.T to be able to reach all the needed endpoints.

Github limitations:

• Sign-in with classic or fine grained "Personal access token" on Github implies we cannot fetch the required approvals count for a PR.
• Sign-in with fine grained "Personal access token" on Github implies we cannot fetch the pipeline status.

Those are limitations that may be solved in the future by Github.

You can reset Pulldog following these steps:

• Close Pulldog
• Open "Keychain Access" on your Mac then click "session" section on the left panel then delete com.natic.pull key
• Delete folder/Users/<username>/Library/Group Containers/group.com.natic.pull

⚠️ You will loose your created smart queries and user preferences.

Providers like Gitlab ask you to log-in again after a certain amount of time. In this case Pulldog will warn you with a red bolt icon. Simply add your account again. Pulldog will know it's the same account and update the credentials accordingly.

No. All credentials are kept private on your machine inside the macOS keychain. Pulldog is a pure macOS client application, it hasn't a server infrastructure for now.

Since Pulldog is not directly a subsidiary of GitHub or GitLab, to avoid this polling mechanism, it would be necessary to set up an intermediate server using a webhook on the repositories we want to monitor. This would allow for real-time notifications for changes. However, aside from the cost and development of such a service, this would also lead to an increase in subscription fees to cover the operational costs. It also brings an important security & privacy aspect on the table. As Pulldog would need to save on server information about you.

A simpler approach is to refresh the PRs at regular intervals, as a mailbox used to do at the time. This is the solution that Pulldog has chosen for now in order to maintain a subscription price cheaper and accessible to the widest audience as well as to guarantee privacy and security by design. Your git data never go or transit to a Pulldog server. Polling works intelligently in harmony with the system, giving it the flexibility to determine the most efficient execution time based on energy usage, thermal conditions, and CPU utilization.
See NSBackgroundActivityScheduler for more detail.

Some data have high cost to be retrieved & aggregated. To keep Pulldog fast & smooth, we get them once you intend to really access the PR for more detail and kept them locally, just in case you later want to quickly have a look at it again.

Github API requires you to have "GitHub Pro or make the repository public" to enable this feature. You can also found some features available for one provider but not for others likes "Delete source branch when merge" , "Merge when pipelines finished" or "Attach a file to a comment".

Pulldog act as an aggregator. If the feature is supported by the provider it will be shown otherwise it will be hidden.