An organization's GitHub page can show a README too: who you are, what you build, how to contribute, and whether you are hiring. It works like a personal profile, with a different repository and a different audience. This lesson builds one.
Create the organization's .github repository
An organization profile README does not live in a repository named after the organization. It lives in:
- A public repository called
.githubin the organization - In the file
profile/README.md(inside aprofilefolder)
For the organization acme, that is acme/.github, file profile/README.md. GitHub shows it on the organization's page once it is there.
Start from an organization layout
In Profile README Studio, click Templates and switch to Organization. These layouts are made for a team: a banner, what you do, featured projects, how to contribute and how to reach you.
In page settings, the username field is called Organization name while an organization layout is open: type the organization's GitHub name there. Cards and links use it the same way as for a person.
Add the organization blocks
Two blocks are made for organizations:
- Contributors wall shows the avatars of everyone who contributed to a repository, drawn by the profile workflow in your
.githubrepository. Set the repository, how many avatars, and how many per row. It is a thank-you and a signal that the project is alive - We're hiring is a banner that sends people to your open roles. Set the text, the link and the colour
Useful from the other groups:
- Featured repos for your main projects, with Show the owner name on cards off, since they all belong to you
- Tech stack icons for what you work with, which helps candidates and contributors
- Social links and Contact for your website, blog and community chat
Write for three readers
An organization page is read by users of your projects, possible contributors and job seekers. Give each one line and a link:
| Reader | What they need |
|---|---|
| Users | What you make, and where the docs are |
| Contributors | Where to start, like a link to good first issues |
| Job seekers | That you are hiring, and where the roles are |
Leave personal stats cards out. Commit counts and streaks describe a person, not a team.
Publish it
Export writes the file for the organization's .github repository, in profile/README.md. Paste it there on GitHub, or use Publish for me with a fine-grained token that has Contents: Read and write on the .github repository (and Workflows: Read and write when it adds the profile workflow).
The guide to organization profile READMEs has more examples.
That was the last lesson. You can now build, fix, automate and publish a profile README for yourself or an organization. If something is missing or does not work as described, the Feedback button in the studio's bar goes straight to the issue tracker.