Start with the work you want to do
An issue is a place to describe and discuss a task, question or bug. A pull request contains a proposed change to the files. You can use either on its own, or link them when a change addresses a tracked task.
For example, an issue might report that the setup instructions are missing a step. A pull request can add that step to the README and give someone a chance to check it before it becomes part of the shared version.
To create an issue, open the repository’s Issues → New issue. Describe what you expected, what happened and how someone can reproduce it. For a proposed improvement, explain the outcome you want. An assignee is the person taking responsibility; labels group related work, such as bugs or documentation.
Open a pull request
First make and push a branch with your change. The everyday Git guide walks through that process. Then open the repository’s Pull requests → New pull request.
- Choose the base: the branch that should receive the change, often
main. - Choose the head: your branch with the proposed change, such as
improve-readme. - Write a short title and explain what changed, why it helps and how you checked it. Include a link to a related issue if there is one.
- Check the diff and select Create pull request. Choose Draft if you want to share work that is still in progress.
The pull request compares your branch with its base. Opening it does not merge anything. While it is open, you can discuss the approach, request a reviewer and push further commits to the same branch.
Contributing to someone else’s public repository without write access? Make a fork, push your branch there and select it as the head of a pull request to the original repository.
Read the diff and give feedback
A diff shows how the proposed files differ: added lines have a +, removed lines have a -, and surrounding unchanged lines provide context. Review the description first, then inspect the changed files. Ask whether the change solves the intended problem and whether the checks cover it.
Comment on a line for specific feedback or add a general comment for a broader question. A submitted review can approve the change, request changes or leave feedback without either decision. Approval records a reviewer’s judgement; it does not itself merge the pull request.
As the author, respond to comments and make any corrections in your local branch. Commit and push them as usual: the same pull request updates automatically. Resolve conversations once the feedback is addressed, and mark a draft Ready for review when it is ready.
The dashboard brings together pull requests awaiting your review, your open pull requests and assigned issues. Inbox helps you follow notifications about work you are involved in.
Understand what is needed before merging
The merge panel explains whether the change is ready and what still needs attention. A check is an automated result, such as a test run. A required review is a person’s approval. A conflict means the proposed changes need to be reconciled with changes already on the base branch.
If a check fails, open its Runs entry and read the failed step’s log. If changes are requested, address the feedback. For conflicts, follow Resolve a merge conflict. Pushing the correction updates the pull request.
When the requirements are satisfied, choose a merge method that matches your team’s practice:
- Create a merge commit joins the branches and keeps the individual commits from your branch.
- Squash and merge combines the pull request’s changes into one new commit on the base branch.
- Rebase and merge applies the branch’s commits in sequence on top of the base, giving them new identifiers.
After the merge, the base branch on Pillion contains the change. Update your local copy before beginning the next task. Closing a pull request without merging ends the proposal without adding its changes to the base.
For maintainers: agree on branch rules
A ruleset is a policy for changes to selected branches. For example, your team can require a pull request and an approving review before updating main. This makes the agreed review process a condition of merging.
Repository administrators configure Settings → Rulesets. Organization owners can also apply rulesets across their repositories. Every applicable ruleset must be satisfied. Pillion uses this ruleset system rather than classic branch-protection settings.
You can also enable AI review for additional feedback. Enabling it and requiring its check to pass are separate choices.