Domain review: repositories

On Thursday, April 15, the session moved to the second area of the outline, working with GitHub repositories, worth 10 to 15 in 100 of the exam. Owen had created and looked after repositories all winter, so most of it felt familiar. His dots were on two skills: repository insights and metrics, which he had rarely opened, and the difference between a template repository and a fork, which he could explain but still hesitated over under time pressure. Priya brought up the trailcheck repository on the meeting room screen and used it as the example for everything.

Creating a repository

A new repository needs an owner, which is a personal account or an organization, a name, and a visibility. Public repositories can be seen by anyone; private ones only by people given access; and organizations on Enterprise plans can also make internal repositories, visible to all members of the enterprise. The creation page offers to add a README, a .gitignore file and a licence at the start, which saves a commit later. A repository can also be created from a template, imported from another version control system, or created by forking.

The difference between a template and a fork is a favourite exam distinction. A template repository is for starting new projects from the same structure; the new repository has a fresh history and no ongoing link, so changes are not meant to flow back. A fork is for contributing to, or building on, an existing project; it keeps the history and the connection, so the fork can propose changes back by pull request and pull in updates from the original. Tidewater made its style-guide repository a template so that each new guidebook starts with the same folders, front matter and checks.

The key repository files

The outline names five files explicitly: README, LICENSE, CONTRIBUTING, CODEOWNERS and SECURITY. Each answers a different question that a visitor or contributor has, and GitHub treats each one specially when it finds it.

Two details are worth remembering. CODEOWNERS can live in the root, in a docs folder or in the .github folder, and its patterns work like .gitignore patterns, with the last matching line winning. And a repository with no LICENSE file is not open source by default: copyright law reserves all rights to the author, so others may view it on GitHub but have no permission to reuse it. The other community health files, such as CODE_OF_CONDUCT.md, SUPPORT.md and issue templates, were covered in MSBA-161 lesson 5 and appear in lesson 9 of this review.

Adding and managing files

Files can be added by pushing commits from Git or GitHub Desktop, or directly in the browser: GitHub lets you create a file, upload files by dragging them in, edit a file in the web editor, and rename, move or delete it, each as a commit with a message. Browser edits on a protected branch offer to create a new branch and pull request instead. Large binary files fit poorly in Git, which stores every version in full; Git Large File Storage keeps pointers in the repository and the files themselves elsewhere, and GitHub blocks individual files over 100 MB unless they use it. For releases, GitHub Releases attach packaged files to a tag, which is how TrailCheck publishes its printable trail-map bundle.

Branches are managed in the repository too. The default branch is what visitors see and what pull requests target unless they choose otherwise; an admin can rename it, and GitHub redirects links and updates open pull requests. Old branches can be deleted after merging, automatically if the repository setting is on, and restored from the pull request page if deleted by mistake.

Insights, metrics and stars

This was Owen's weakest skill in the area, so Priya opened the Insights tab of trailcheck and went through it page by page. Insights shows activity and health without any setup.

Not everyone can see every page. Pulse, contributors and commit graphs are visible to anyone who can read the repository, so on a public repository anyone can look. Traffic is restricted to people with write access, because it reveals how a project is used. The dependency graph needs to be enabled for private repositories, and on public repositories it is on by default. Exam questions occasionally ask why a person cannot see a page, and the answer is usually their role, not a missing feature.

Organizations with GitHub Team or Enterprise can also see organization-level insights and, on Enterprise plans, metrics dashboards for Copilot and other features. The outline mentions dependency insights, which for an organization summarize the dependencies across its repositories and any known vulnerabilities in them.

Stars are a way for people to bookmark a repository and show appreciation. The star count is a rough signal of interest, and starred repositories appear in the person's own list for later. Starring is different from watching, which controls notifications, covered in lesson 5. Neither gives access or permissions.

Repository settings worth recognizing

The repository Settings tab is visible only to people with the Admin role, and a foundations candidate should recognize what lives there rather than every option. General holds the name, the default branch, template status, the features to show (issues, wiki, discussions, projects), the merge buttons to allow, whether to delete branches automatically after merging, and the "danger zone" with visibility changes, transfer, archive and delete. Collaborators and teams grants access. Branches and Rules hold branch protection rules and rulesets. Actions, Webhooks, Pages, Environments and Secrets and variables configure automation and publishing. Code security turns on the dependency graph, Dependabot and secret scanning features.

Turning features on and off per repository matters more than it sounds. A repository can hide Issues if the team tracks work elsewhere, hide the wiki if documentation lives in a docs folder, and show Discussions for community questions. Questions sometimes describe a missing tab, such as "contributors cannot find Discussions", where the answer is that an admin has to enable the feature in General settings.

Maintaining a repository

Maintenance questions ask what good practice looks like over time. A healthy repository has a current README and licence, a clear contributing guide, labels and templates that make triage easy, branch protection on main, and automated checks. Stale branches are deleted after merging. Issues that will never be done are closed with a reason, as not planned, rather than left open. Dependencies are kept up to date with Dependabot. Topics and a description make the repository easy to find. A repository that is finished but still useful can be archived, which makes it read-only, keeps it visible, and tells visitors it is no longer maintained; it can be unarchived later. Deleting is permanent after a short restore window and breaks every link, so archiving is the usual choice for old projects.

Tidewater archived the second-edition guide repository when the third edition started, so readers who had bookmarked old corrections could still read them. MSBA-161 lesson 12 covered the transfer of Malik's open-trail-report repository into the organization, which kept its stars, issues and history and redirected the old address.