Project vs Repository in GitHub

Question

In GitHub, what is the conceptual difference between a project (that can be created inside a repository) and a repository?

I've seen several similar questions (here, here and here) in SO, but none of them explains what is a GitHub project, what is a GitHub repository and when to use each one of them.

I would appreciate if someone can explain each term, and provide an example of when to use/create each one. For instance, if I have several prototype applications, all independent of each other, what do I create in order to manage in an organized way the source code for all of them?

Answer 1

Fact 1: Projects and Repositories were always synonyms on GitHub.

Fact 2: This is no longer the case.

There is a lot of confusion about Repositories and Projects. In the past both terms were used pretty much interchangeably by the users and the GitHub's very own documentation. This is reflected by some of the answers and comments here that explain the subtle differences between those terms and when the one was preferred over the other. The difference were always subtle, e.g. like the issue tracker being part of the project but not part of the repository which might be thought of as a strictly git thing etc.

Not any more.

Currently repos and projects refer to a different kinds of entities that have separate APIs:

• https://developer.github.com/v3/repos/
• https://developer.github.com/v3/projects/

Since then it is no longer correct to call the repo a project or vice versa. Note that it is often confused in the official documentation and it is unfortunate that a term that was already widely used has been chosen as the name of the new entity but this is the case and we have to live with that.

The consequence is that repos and projects are usually confused and every time you read about GitHub projects you have to wonder if it's really about the projects or about repos. Had they chosen some other name or an abbreviation like "proj" then we could know that what is discussed is the new type of entity, a precise object with concrete properties, or a general speaking repo-like projectish kind of thingy.

The term that is usually unambiguous is "project board".

What can we learn from the API

The first endpoint in the documentation of the Projects API:

• https://developer.github.com/v3/projects/#list-repository-projects

is described as: List repository projects. It means that a repository can have many projects. So those two cannot mean the same thing. It includes Response if projects are disabled:

{   "message": "Projects are disabled for this repo",   "documentation_url": "https://developer.github.com/v3" } 

which means that some repos can have projects disabled. Again, those cannot be the same thing when a repo can have projects disabled.

There are some other interesting endpoints:

• Create a repository project - POST /repos/:owner/:repo/projects
• Create an organization project - POST /orgs/:org/projects

but there is no:

• Create a user's project - POST /users/:user/projects

Which leads us to another difference:

1. Repositories can belong to users or organizations
2. Projects can belong to repositories or organizations

or, more importantly:

1. Projects can belong to repositories but not the other way around
2. Projects can belong to organizations but not to users
3. Repositories can belong to organizations and to users

See also:

• https://help.github.com/articles/about-project-boards/

I know it's confusing. I tried to explain it as precisely as I could.

Answer 2

GitHub recently introduced a new feature called Projects. This provides a visual board that is typical of many Project Management tools:

A Repository as documented on GitHub:

A repository is the most basic element of GitHub. They're easiest to imagine as a project's folder. A repository contains all of the project files (including documentation), and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private.

A Project as documented on GitHub:

Project boards on GitHub help you organize and prioritize your work. You can create project boards for specific feature work, comprehensive roadmaps, or even release checklists. With project boards, you have the flexibility to create customized workflows that suit your needs.

Part of the confusion is that the new feature, Projects, conflicts with the overloaded usage of the term project in the documentation above.