Proposal / Feature Request: Pin Repositories

[dschier-wtd]

Hi team,
first let me say: It's awesome what you are doing here!

I wanted to propose a feature, currently existing in many other SCM UIs. Having the option to pi a specific amount of repositories to the top would be awesome.

Description

Pinning a repository to the top of an organization can be helpful for many use cases.

• putting Skeletons / Templates / Conventions / Concepts on top
• featuring repositories in an organization
• highlighting important repositories

Mockup / Ideas

I am seeing three possible options here to have a pinned repository:

1. Pinned Cards

This option will lead the viewers attention directly to the featured / pinned / important repositories.

• limitation will be needed (3 - 8)
• organization of the cards should be possible

2. Featured Repository

This option will take use of the unused space on the right side the same way as people and teams are featured.

• limitation may be needed (5 or so?)
• not as viewable as proposal 1
• may be easier to implement
• will use more unused space and not "push" the content down

3. Pinned List

The last option may be the simplest way. Pinning a repository just means, that it will stay on top of the repository list.

• very limited ui development
• context "this is a repo" is clearly visible
• is limited to the amount of "shown" pages
• defining a limit may be need (5 seems ok)

[realpixelcode]

This would be really nice!

[lhinderberger]

This would also be very useful for individual user profiles, in addition to organizations.

[Mikaela]

I stumbled upon this with individual user profile as I have "real" repositories and then now I have a tutorial repository for learning. The result is that whenever I push to the tutorial repository it gets pushed to top and takes visibility from the real repositories that I would actually like to show.

[ghost]

Yeah, that would definitely be awesome !

[era]

I may work on this feature if no one started yet, at least on the backend.

Regarding the backend, independent of the option we go with, I imagine we will have to:

• Add a Pinnedflag to the repo table.
• Add a configurable* limit for the number of pinned repo

*not sure what this would mean, but I imagine different gitea owners may want different configurations for this, right?

Regarding the API, should we create a new API to pin? Or should we use the editRepo? Should users be able to pin while creating a new repo?

[Eekle]

I think I'd like to tackle this issue.

Does it satisfy the requirement if pinned repositories are simply listed first on a user/org page?

Do we actually need a limit on how many repositories can be pinned? If it's just a sorting feature, then it can be up to orgs/users to determine what suits them.

For the API, are we happy to just extend PATCH /repos/{owner}/{repo}?

Is it preferable to have POST /repos/{owner}/{repo}/pin, DELETE /repos/{owner}/{repo}/pin.

[lunny]

Maybe max limit is 6 and 3 for one line.

[Eekle]

Is this presuming that we use the "3 tiles" format, suggestion no.1? I was going to go with no.3 for ease of implementation.

[ell1e]

This is the latest draft if I'm not mistaken, right?

So wouldn't it based on that make sense to make Public Activity the default and left-most tab?

Since it'd now be possible to pin repos, users could present their work centered and up front anyway, so the next most interesting info is probably what they've been recently up to and not the entire exhaustive list of random smaller other repos (when you've already seen their standout projects pinned!). It might make Gitea feel more social and alive, seeing more prominently the concrete activity and comments.

[delvh]

The only thing I can somewhat guess would be that you need a dropdown when pinning to decide where to pin it to, with the options being you, or the orgs you have admin rights in. If you don't have admin rights in any org, we should probably shortcut to directly pinning to your own page.

Originally posted by @delvh in #19831 (comment)

It seems like you're suggesting that orgs should also be able to pin any repository to their profiles - not just ones tha they own?
I thought we were suggesting users could pin anything, but orgs could only pin their own repos.

Originally posted by @Eekle in #19831 (comment)

but orgs could only pin their own repos.

Would that be important to limit though? Maybe it should also be unrestricted.

Originally posted by @ell1e in #19831 (comment)

I'm moving the discussion now here as it is more appropriate here.

So, at the moment, we have the following options:

• allow any owner to pin any repo they can see
• allow users to pin any repo they can see, orgs only their own repos
• allow every owner only to pin their own repos

[Eekle]

Repeating my concern from #19831 (comment)

I think the UI could really get in the way of function here. Pinning a repository to its owner's profile is going to be the most common use case, probably overwhelmingly common in the case of orgs.

If we allow arbitrary pinning to org+user profiles, I think it could easily muddy the experience of the common case.

---

Perhaps if the main pin button were for "pin/unpin from owner", but we include a dropdown for more intricate options (pin/unpin from active user, or from other administrated orgs), then that might be nice.

[delvh]

Yes, that was also what I meant.

---

Also, when we implement 1 or 2, we always have to filter all pinned repos for whether the current viewer can see the corresponding repos as we can otherwise have security issues where unallowed users can see that a specific repo exists.
Furthermore, the current approach of a denormalized data structure is not a good idea in that case as we probably need to use nestedJOINs if we don't want serious performance drawbacks.

[Eekle]

I suppose we have to check visibility no matter what, though? For things like private repos?

[delvh]

Makes sense. As I mentioned, the approach of storing a JSON list is in that case probably not a good idea anymore.
Unless of course you have an easy idea how to ensure that a user can really see a pinned repo with the current mechanism…

[Eekle]

No I agree with you. It feels like a Pins table may be in order.

[delvh]

Well, probably rather a PinnedRepo table, PinnedIssue will most likely also exist at some point.

[Eekle]

Smart. One thing to consider is that you might lose visibility of a repo you've pinned. For example if it gets made private, or you lose access to an org.

In those cases, I guess we can just leave the entries in the PinnedRepo table - and then the next time pins get updated for that user/org, we can clean up any invalid entries. That'll save the work of trying to work out all the operations that might invalidate pins.

[ell1e]

or you lose access to an org

Shouldn't a pin depend on 100% unrestricted public visibility anyway? If I have access to an org but nobody looking at my profile does, I'm not sure it should be allowed that I pin anything from that org. After all others can't then go and look at it, that would be confusing.

[Eekle]

or you lose access to an org

Shouldn't a pin depend on 100% unrestricted public visibility anyway? If I have access to an org but nobody looking at my profile does, I'm not sure it should be allowed that I pin anything from that org. After all almost nobody can then go and look at it anyway, that would be very confusing.

It would be intuitive to me if you could pin whatever, but other users wouldn't see it on your profile unless they had visibility of it too.

[delvh]

Yep, that's also the approach I had in mind.

[ell1e]

Right, I guess that has some use especially in corporate instances where the majority might be private but still be visible to a lot of people and hence worth pinning. I can however see it leading to some confusing on mostly public instances when users pin something there that they thought was (and is) private, then wondering why that even worked and maybe not realizing it's not really shown on their profile anyway.

[delvh]

What is GitHubs approach here? Do they allow pinning private repos?

[delvh]

Also, pinning private repos even makes sense:
If you want to quickly find a repo again, that is used widely, but only internally in your organization, then pinning a private repo would be the equivalent of a bookmark/ quick access.

[Eekle]

Right, I guess that has some use especially in corporate instances where the majority might be private but still be visible to a lot of people and hence worth pinning. I can however see it leading to some confusing on mostly public instances when users pin something there that they thought was (and is) private, then wondering why that even worked and maybe not realizing it's not really shown on their profile anyway.

The current implementation marks a repo as Private in the pin card.

This is the same marking used on the actual repository listing on the profile.

So I hope that is enough of a cue to a confused user that "Oh this is listed as private, so they've taken it into account."

[Eekle]

I suspect given the scope of changes suggested relative to the first implementation, it's going to have to be pretty much all torn out. The only reusable work is likely to be the pin card implementations on profile pages.

[ell1e]

The current implementation marks a repo as Private in the pin card. [...] So I hope that is enough of a cue

Omg yes, that looks perfect! I love that. This is going to be pretty cool if it all works out as planned.

[BRAVO68WEB]

Hey guys, is their any update on this?

[Ashvith10]

What's the status of this issue?

[Ashvith10]

Haven't got any response yet, but I am still looking for a workaround. I have a few projects that I would like to highlight in my developer portfolio web-app. Now, this would take advantage of the Gitea/Codeberg API, where I'll be able to choose projects that will be shown on my website. In GitHub, you can do this conveniently by pinning and using that specific API to highlight pinned projects, but I'm not sure if there's any similar mechanisms for Gitea/Codeberg?

[ell1e]

@Ashvith10 there actually is kind of a workaround now! You can do both profile readmes and org readmes in the latest gitea version, which looks like this in practice: (me on codeberg with profile readme). and you can just put projects there! (the org readme update might not have reached codeberg yet, but it should soon.)

as for using that from your website, maybe you could use some hidden HTML comment in your profile readme or such that allows to extract things in a more automated fashion, and parse that when fetching your profile from your website script.

[KaKi87]

in the latest gitea version

Since v1.20.1, actually.

[ell1e]

Not the org readmes. anyway, it should reach codeberg soon.

in my personal opinion these readmes are so good, that it even replaces pinning in some sense. like, i personally don't think pins add much with this feature now present, but that's just my opinion of course.

[Ashvith10]

@ell1e unfortunately, that isn't what I'm looking for, I was talking about the Codeberg REST API, actually. So, if there was a way to pin projects, I could access that particular API from the web app that I'm hosting on a cloud platform.

So far, I've come across this:

curl -s https://codeberg.org/api/v1/user/starred -H "Authorization: token <hidden-for-security-reasons>"

But this also includes other starred users, which means pointless overheads.

[ell1e]

you can put stuff into the HTML comments into a markdown file like the profile readme, and i think they render into the final output, usually. so it's possible to hide machine readable data in there.

[carlosfelgueiras]

Me and @DanielMatiasCarvalho are working on this.