Organizations, teams, repositories
Beginner GitHub UI
Why this matters
Everything on GitHub hangs off two containers: an account and a repository. Understanding how teams sit between them is what lets you answer "who can see this?" and "where should this new repository live?" without guessing.
The shape
| Thing | Is | Contains |
|---|---|---|
| Personal account | You | Your own repositories |
| Organization | A company, team or community | Repositories, teams, members, billing |
| Team | A named group of people inside an organization | Members, and access to repositories; can contain other teams |
| Repository | One project's Git repository plus its issues, pull requests and settings | Code, branches, tags, releases, wiki, Actions |
The address follows the container: github.com/<owner>/<repository>, where the owner is your username or the organization name. There is exactly one level; a repository is never inside another repository or inside a team.
Personal or organization?
Anything with more than one contributor belongs in an organization, even a small one. The reason is ownership rather than features: a repository in a personal account belongs to that person, and when they leave, so does it. Organization repositories outlive their members.
Free organizations are enough for most teams. Private repositories, unlimited collaborators and Actions minutes are all included; the paid tiers add rulesets on private repositories, required reviewers, and audit tooling.
Teams
A team is how an organization avoids managing access one person at a time. Give the docs team Write on the documentation repositories, and every writer who joins the team gets it automatically.
Two features earn their keep:
- Nested teams. A
docsteam inside anengineeringteam inherits its parent's repository access, so a child team can only add access, never remove it. - Mentions. Writing
@northwind-trails/docsin an issue or pull request notifies the whole team, which is the correct way to ask "someone from docs, please look".
Teams also power code owners: a CODEOWNERS file can name a team as the required reviewer for a path (lesson 10.5).
Repositories
What sits inside one, beyond the files:
| Part | What it is |
|---|---|
| Code | The Git repository: branches, tags, commits |
| Issues | Work items (lesson 10.6) |
| Pull requests | Proposed changes (lesson 10.7) |
| Actions | Automation (lesson 10.10) |
| Wiki, Projects, Discussions | Optional, switched on per repository in Settings |
| Settings | Access, branches and rulesets, secrets, Pages |
A repository can be transferred to another owner, and can be forked into your own account, which is how contribution to projects you cannot push to works (lesson 7.7).
Renaming and moving
GitHub redirects the old address after a rename or transfer, both for the web and for Git, so a clone with the old remote keeps working. That is a courtesy, not a guarantee: update your remote, because the redirect stops the moment someone creates a new repository with the old name.
$ git remote set-url origin git@github.com:northwind-trails/trailguide.gitHow to do it
Nothing here is a Git command, but the address you clone is where the structure shows up:
$ git clone git@github.com:northwind-trails/trailguide.gitOwner then repository, always two segments. If someone gives you a GitLab-style path with three or more, it is not a GitHub URL.
Clone from GitHub in the Command Palette lists the repositories you can access, grouped by owner, which is a fast way to see which organizations you belong to.
File → New → Project from Version Control → GitHub lists your accessible repositories by owner. Organizations appear as separate groups.
GitLab's containers are groups, which nest into subgroups, and projects. Access can be granted at any level and is inherited downwards, so GitLab uses the container tree where GitHub uses teams. See lesson 9.2.
- Your organizations are listed under profile photo → Your organizations.
- Inside one, Teams lists teams; People lists members; Repositories lists repositories.
- A team's page has Repositories, where its role on each is set, and Members.
- New repository is created from the + menu; choose the owner, which decides whether it is personal or the organization's.
- Settings → General at the bottom holds Transfer ownership, Archive and Delete, all of them Admin-only.
Common mistakes
- A shared project in a personal account. It leaves when its owner does.
- Adding people to repositories one at a time, then discovering nobody knows who has access to what.
- Assuming repositories nest. They do not; a
docs/style-guiderepository is one repository whose name contains no slash. - Relying on the redirect after a rename. Update the remote.
- Creating a team per repository. Teams should map to people who work together, not to the code.
Try it yourself
Goal: see the structure from the inside.
- Open an organization you belong to, or create a free one for practice.
- Look at People, Teams and Repositories, and work out which of the three gives you your access.
- Create a team, add yourself, and give it Read on one repository.
- Check the repository's Settings → Collaborators and teams and find your team listed.
- Compare the repository's URL with a GitLab project URL from lesson 9.2 and note the difference in depth.
Expected result: you can name the path by which you have access to a repository: directly as a collaborator, through a team, or as an organization owner.
Show solution
Step 2 is the point. On a well-run organization the answer is almost always "through a team", and that is the sign of access being managed rather than accumulated. If the answer is "I was added personally to eleven repositories", that is a good thing to raise.