Setup a maintainer account with Polar

Creating a new account

Don't have an account already? Signup as a maintainer now to easily create both an account (GitHub Login) and install the Polar GitHub app at once.

Screenshot of signup page on Polar

This signup flow will ensure you:

Create a Polar account using your GitHub Login (OAuth) Covered in the next section below.
Install the Polar GitHub app thereafter (redirect) - granting access to select repositories to use with Polar for issue funding.

Covered further down below: Install GitHub App

Signup & login on Polar is made super easy with GitHub Login (OAuth).

Screenshot of GitHub OAuth with Polar

We require GitHub Login (OAuth) for maintainer accounts on Polar. In order to:

Verify your GitHub account
Install & manage the Polar GitHub app (next step) to enable funding towards issues across your select repositories.

We also use this login connection to:

Reserve the same username/orgname on Polar
Request read-only access to your email addresses so we can communicate with you, e.g send notifications upon new pledges etc.
Create a matching, public, profile for you on Polar (avatar, username, bio etc)
Setup a public page under https://polar.sh/<username> for maintainers - showing fundable issues
Show your profile in connection with funding issues (optional)
Recommend maintainers/repositories to fund based on your GitHub stars

Once authorization has been granted, you will be redirect to GitHub again to install the Polar GitHub app on the repositories you want.

important

What does 'Act on my behalf' mean?

This is a default notice from GitHub in all their OAuth authentication flows. See this ticket from the wider community asking GitHub to improve the copy.

Rest assured, we do not do anything on your behalf without a delibrate action performed by you via Polar for an explicit, clear & desired outcome by you.

Specifically, we make it easy for you - as a maintainer - to comment on issues you manage via Polar. In case you want to promote funding or notify contributors about granted rewards via an in-line comment. No such comment is automated, required or hard-coded (you can edit them freely in our UI) and they require you to manually submit them each time.

Upgrade an existing account

Funded an issue on Polar and already have an account? Or want to connect a GitHub organization and its repositories to use with Polar? We got you.

Enable personal maintainer account

Screenshot of enabling personal maintainer mode in Polar

Click Get Started under the Become a creator card in the sidebar
You're presented with an onboarding page to enable maintainer mode (see above)
Click Connect Repositories
Redirected to the GitHub App Installation flow - covered next in Install GitHub App

Connect GitHub organization(s)

Screenshot of adding maintainer organizations in Polar

You can use Polar personally and for GitHub organizations you're an admin of. It's super easy to connect additional organizations and their repositories.

Click on your profile in the Polar dashboard
Click Add organization in the dropdown
You're presented with an onboarding page to connect an organization to Polar
Click Add GitHub Organization
Redirected to the GitHub App Installation flow - covered next in Install GitHub App

Install the Polar GitHub App

Amazing, you now have an account setup and have been redirected to install the Polar App on GitHub by either:

Signing up as a new maintainer on Polar
Enabling maintainer mode for an existing account
Or, perhaps you're in the process of connecting an additional GitHub organization to use with Polar

All roads lead to Rome, or in our case the GitHub App installation flow for the Polar app.

GitHub's Installation Flow

Choose account or organization: GitHub will ask you to choose which account or organization to install Polar for in case you have access to more than one.
Review & Install Polar App: For selected repositories under the chosen GitHub account or organization. See below.

Polar App Installation at GitHub

Choosing repositories

Choose which repositories Polar should have access to. Access is required to easily embed the Polar funding badge on issues. However, you're always in control of which issues to badge across the repositories you've granted access to.

All Repositories

Every, single, repository is synced with Polar - including future ones
Pros: Automatically use Polar freely across your repositories now and in the future.
Cons: You sync a lot and more than might be needed or desired.

note

Private repositories & forks are synced too

We sync all the repositories given during installation. Including private repos & forks.

However, we don't expose issues related to private repos except to those who can access it on GitHub. It's supported to allow maintainers to connect private repositories to try Polar with.

We also sync forks currently. Supporting cases where forks have superseded the original within the community.

Both of the above are likely to be deprecated features in the future.

Select Repositories

You choose exactly which repositories Polar should have access to
Pros: Complete control. Gradual expansion. Great starting point.
Cons: You need to manually add repositories.

note

Can I change repositories later?

Of course, you can always change repository access at any point in your GitHub settings for the Polar app.

Required permissions

Read access to metadata

We store this data to create a trustworthy user experience for your backers. Showing repository context on the issue pledge page for backers as an example, e.g avatar, name, description, stars, license etc.

Read access to issues & pull requests

We synchronize all your issues and pull requests in order to deliver our core offering. Keeping track of all issues, their contributions and current status - updating it in near real-time (webhooks). Enabling funding to seamlessly work within your existing workflow & across Polar services.

Write access to issues & pull requests

Polar funding is designed to be deeply integrated within the GitHub workflow & experience. By enabling you to easily embed the beautiful and non-intrusive Polar funding badge directly within selected issues (at the bottom of their description). We need to be able to write to issues in order to achieve this. Of course, we only embed the badge based on your settings and desired issues to badge.

Next Step

Welcome onboard - we're excited to support you here at Polar! It's time to customize the Polar Badge and start embedding & promoting it.

Customize the Polar Badge

Epic! Polar is now installed across your chosen GitHub repositories and you've been redirected back to Polar. We're at the last - required - step: Customize the Polar Badge settings for your repositories.

GitHub Issue with Polar Badge

Goal

Users stumble upon impactful & relevant issues to them. Usually, they would hammer the 👍 and perhaps even write a "+1" comment. But now, they also see that they can do more; they can collectively pool funding towards it to support you and your contributors in your efforts to complete it.

Beautiful & non-intrusive SVG
Promotes funding - link to Polar pledge page for given issue
Embeddad at the end of the GitHub issue description
Seamlessly integrated with GitHub vs. creating noise in issue threads via comments
Updates automatically to show funding progress & backers
Promote an allocated reward to potential contributors - a percentage of funding (optional)

Checkout an example on a GitHub issue: SerenityOS/serenity#22179

Let's get this beaut setup for you.

Setup

Once you've installed the Polar GitHub App you'll be redirected back to Polar and the screen below. Let's go through it - together.

Badge Settings

Markdown description

Custom markdown text to be inserted before the Polar Badge. Great way to offer additional and personal context. We offer a default suggestion, but you can easily edit it and even remove it entirely.

Minimum funding amount

The minimum amount required for funding by individual backers (default is $20)

Public rewards

Enable & promote a default percentage split of the funding pool with potential contributors who help squash an issue.

tip

Missing something? We'd love to chat and improve the product based on your feedback!

You can submit a feature request via GitHub (we're building open source). You're also more than welcome to join our Discord. Relevant links

Embed Settings

So we have our badge setup & ready - amazing! Let's configure how we want to embed it for each repository.

Manual: Issues by Label

This is the default setting and a great way to try things out. You then have complete control of which issues you want to embed the Polar Badge on using the label Fund (case insensitive).

You can label via GitHub directly and see the badge embedded within seconds
You can label & badge an issue with one-click through the Polar dashboard

Automated: All Issues

Ok, you're loving it. Let's unleash it across all issues to promote funding to our community and let them help vote & fund the most impactful efforts. Combined with using rewards to distribute it across your contributors. Just like tRPC has.

All will ensure all future issues are badged automatically & directly upon creation
You'll get the option to badge all existing - open - issues too. However, for safety, we show how many issues would be updated and require you to explicitly confirm & trigger this action.

note

How GitHub issue ordering is affected by multiple updates

Since we update the issues to embed the Polar Badge the issues will get an updated modified_at timestamp.

By default, GitHub issues is sorted by created_at so it's not impacted unless you specifically sort by modified_at.

However, when & if you select to badge all existing - open - issues, we do so in a batch and in reverse chronological modified_at order. So that even though we update them we do so in a way that should retain their previous order. We cannot promise, however, that it will guaranteed.

Next Step

You're now officially done with the maintainer onboarding 🎉 Go ahead and badge all the issues you want & checkout how you can promote it further for a higher chance of success.

We're honored to have you onboard! Don't hesitate to reach out and share how we can improve at any point. We have ambitious plans & a lot of exciting features in store.

Documentation

Issue Funding

FAQ

Setup a maintainer account with Polar