Taking contributions

Anyone signed in can send a stack to a public repository through their own lane (Contributing through a lane). This page is for the repository's maintainers.

Review and land a lane#

Open lane reviews that no maintainer has approved appear in your Queue as Contribution. The repository page lists every lane under Lanes.

Check a lane out to try it or fix it up:

gs checkout @eve/fix-typo
gs amend --no-edit   # your patchset is recorded as yours
gs push
gs submit

Any writer can land a lane. Its required checks run as part of the land: the land pushes the lane to the GitHub mirror's CI branch, waits for the checks, then lands. A lane that changes .github/ needs an owner's LGTM.

An LGTM from someone without write access shows on the review and never counts toward the landing policy.

Ask for a CLA#

Name the agreement in .gitstack/policy.toml and land it:

cla = "CLA.md"

Contributors agree on their lane's review page, or with gs cla agree. A lane lands only once its contributor agreed to the CLA as the base branch has it, even when you wrote every commit in it. Each commit must also be authored with the contributor's email or a maintainer's; a commit by anyone else, or with no email, refuses the land. A noreply address counts only as the contributor's, since anyone can type a maintainer's. Editing the CLA asks every contributor to agree again.

Moderate#

• Hide a comment from its menu; maintainers can still read it and show it again.
• Block a user from a comment, or in the repository's settings under Blocked. Their comments and LGTMs are hidden, their pushes and comments are refused, and their lanes are dropped.
• Making the repository private drops every lane.

Keep the GitHub mirror honest#

People who find your project on GitHub will open pull requests there. Merging on GitHub would skip your review, the landing policy and the CLA. To take changes only through lanes:

Have the GitStack App close pull requests. Add this to .gitstack/policy.toml:

[mirror]
pull_requests = "close"

The App then comments on each new pull request with the way to contribute through a lane, and closes it. Without the key, pull requests stay open on GitHub.

Add a CONTRIBUTING.md to the repository, so GitHub shows contributors the way in:

# Contributing

This repository takes changes on GitStack. The GitHub repository is a
read-only mirror, so pull requests here are closed.

1. Install gs: `curl -fsSL https://gitstack.sh/install.sh | sh`
2. Sign in: `gs login`
3. Clone: `gs clone <owner>/<repo>`
4. Commit on a branch, then run `gs submit`.

The full guide: https://gitstack.sh/docs/contributing-through-a-lane

Let only GitStack push the default branch. In the GitHub repository's settings, under Rules, Rulesets, import this ruleset, with the GitStack App's ID as the bypass actor:

{
  "name": "Only GitStack pushes the default branch",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [{ "type": "update" }, { "type": "deletion" }, { "type": "non_fast_forward" }],
  "bypass_actors": [{ "actor_id": 0, "actor_type": "Integration", "bypass_mode": "always" }]
}

Replace 0 with the App's ID. The repository's settings page on GitStack warns you when a rule would refuse GitStack's own pushes.

Keep deploy secrets out of reach. A lane reaches GitHub only through a maintainer's land, but the push to the CI branch runs the workflows the lane carries. Put deploy secrets in GitHub Environments that only protected branches can use, and set the repository's default workflow permissions to read-only (Settings, Actions, General, Workflow permissions).