Set up a repository

This tutorial is for maintainers who want the contributors of a repository to sign agreements. You need the role admin or maintain of the repository, and the right to install GitHub Apps on its account or organization.

The site must already have its GitHub App configured. If you run the site, first go to Set up the GitHub App and choose the recommended submission form, manifest CLI flow or manual creation. Then return here to install that app and activate repositories.

1. Write the agreements

An agreement is a file in a repository on GitHub, such as agreements/ai-policy.md. Markdown files are shown formatted, other files as text. The agreements can be in the repository itself or in another repository, for example one repository with the agreements of all projects of an organization.

Tag the commit of the agreement, so that it does not change by accident:

git tag ai-policy-v1
git push origin ai-policy-v1

2. Add the configuration file

Add .github/agreements.yml to the default branch of the repository:

version: 2.0.0
agreements:
  ai-policy:
    name: AI Policy
    ref: ai-policy-v1
    repository: https://github.com/PyCalendar/ai.pycal.org-example.git
    path: agreements/ai-policy.md
    pr:
      labels: ai-policy-accepted

All fields are described in The configuration file. The example repository PyCalendar/ai.pycal.org-example contains two test agreements.

3. Install the GitHub App

Sign in on the site with GitHub and open Setup. Select Install the GitHub App. GitHub asks you to choose the repositories and to accept the permissions listed in Permissions of the GitHub App. Afterwards GitHub sends you back to the page Setup.

The site renews expiring GitHub user tokens automatically while you use setup. If it shows Your sign in with GitHub has expired, sign out and sign in again: the stored authorization can no longer be renewed. If GitHub is temporarily unavailable, try again later.

4. Add the repository

On the page Setup, select Add next to the repository. The site reads the configuration file and the agreements. If something is wrong, it shows the error with a link to how to solve it, and the repository is not added.

Once added, the open pull requests get a check for each agreement, and those of people who signed get the labels of pr.labels.

5. Enter an email address

When a new version of the site needs more permissions, the site writes to the address of the installation and to its administrators who have an email address on GitHub. Enter the address next to the installation on the page Setup.

Changing the agreements

When you change the configuration file or the file of an agreement in the default branch, the site reads it again. A new commit of an agreement needs a new signature: the labels are removed from the pull requests of people who did not sign the new version, and they see what changed when they open it.

Make the checks required

To merge only pull requests whose authors signed, make the checks such as ai.pycal.org/ai-policy required in a rule of the default branch on GitHub.