Connecting GitHub
A part can send its inventory from CI with watchdep scan, or be connected through GitHub, or both. Connected through GitHub, the server takes the part’s inventory itself, from the repository, on every push to the production branch and every night. This page says exactly what that access allows, how to set it up, and what it cannot see.
What the App can read
watchdep connects through its own GitHub App, which you install on the accounts and repositories you choose. Said plainly:
- The App asks for read access to contents and metadata only, never write. It cannot push, open pull requests, or change settings.
- GitHub cannot limit an App to some files. On the repositories you choose, the App could read every file.
- watchdep fetches only dependency files: lockfiles, manifests, version files, Dockerfiles and
watchdep.yml, by path. It never fetches source code. - If you want watchdep to have no access to your repositories at all, use the CLI route instead:
watchdep scanin your CI sends only the inventory. See The Action and CI.
Install it
Owners and admins install the App on a GitHub account from Settings, GitHub (“Install it on an account”), and choose on GitHub whether it sees all repositories or only some. When GitHub sends you back, the installation is claimed for your workspace, but only if the return carries a link signed for this workspace and this person within the last hour, and GitHub confirms that you can reach that installation: the App asks you to authorize it while installing, and watchdep checks the installation is among your own. A hosted copy refuses a claim without that confirmation, so nobody can claim someone else’s installation by guessing its number; a self-hosted copy checks it whenever GitHub sends it. An installation already claimed by another workspace stays there.
Settings, GitHub lists each installation (the account, all or chosen repositories, and whether it is active, suspended or removed) and every part linked to GitHub with its last fetch or error.
Link a part
In a part’s settings, “Connect through GitHub” lists the repositories your workspace’s installations can see. Choose one, and optionally a folder inside it (a service in a monorepo). A part can be linked only to a repository its own workspace’s installation can see.
Linking takes a first inventory at once. The part’s page then says how it is connected, for example “Connected through GitHub (prospec360/api) and the CLI”. Owners and admins can “Fetch now” at any time.
A part connected only through GitHub shows “use not checked” on its findings: the code check runs only in the CLI, where the code already is.
How an inventory is taken
- watchdep takes the head commit of the part’s production branch (or the commit that was pushed).
- It asks GitHub for the repository’s file list at that commit: paths and sizes, never contents.
- It reads the part’s
watchdep.yml, if there is one, so its ignore list applies. - The same readers the CLI uses decide which of those paths to read. So the GitHub route reads exactly what the CLI route reads, and never a source file.
- Only those files are fetched (at most 2,000 files, each at most 25 MB), into a temporary folder, and read as the CLI would read them, including pulling the public base images named in Dockerfiles and
watchdep.yml. - The inventory is received like one from
watchdep scan, recorded as taken through GitHub at that commit and branch, and checked.
The same files read through GitHub and through the CLI give the same inventory, apart from how, when and at which commit it was taken.
What it cannot read is shown
Anything that could not be fetched is listed as not read, so the inventory is incomplete and never reads as clean: a file GitHub would not give, a file that is too large, more dependency files than watchdep fetches, or a file list GitHub cut short for a very large repository. A base image that cannot be pulled (a private registry, or a build argument with no default) is also listed as not read. For private images and images built in CI, run watchdep scan --image in CI, where the image is.
Pushes and the nightly pass
- Pushes. GitHub tells your copy about every push. A push to a linked part’s production branch (or the branch
watchdep.ymlpins withproduction_branch) takes a fresh inventory at the pushed commit. Pushes to other branches and branch deletions do nothing. - Every night at 01:45 UTC, every part linked to GitHub is fetched again, which catches any push that was missed.
- Suspended or removed. An installation suspended or removed on GitHub is marked so, its parts say so in deep orange, and nothing is fetched until it is restored.
- A failed fetch is recorded on the part (on its page and in Settings, GitHub), and the part’s last inventory stays as it was.