Add repository config info

docs/content/setup/repository.mdx

@@ -5,3 +5,118 @@ status: Alpha
 ---
 
 export { Layout as default } from '@issue-ops/gatsby-theme-doctocat-typescript'
+import {
+  Do,
+  Dont,
+  DoDontContainer,
+  Note
+} from '@issue-ops/gatsby-theme-doctocat-typescript'
+
+This page outlines recommended configuration settings for IssueOps repositories.
+For instructions on how to create a repository, see the
+[GitHub documentation](https://docs.github.com/en/get-started/quickstart/create-a-repo).
+
+## Visibility
+
+IssueOps works best when your repository is accessible to users who need to
+submit requests. Depending on if the repository is owned by an organization or a
+user account, you can set the visibility to one of the following:
+
+| Owner        | Visibility             |
+| ------------ | ---------------------- |
+| Organization | `public` or `internal` |
+| User         | `public`               |
+
+Alternatively, if you only want to allow specific users to submit requests, you
+can set the visibility to `private` and add those users as
+[collaborators](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository).
+
+## Permissions
+
+Users only need `read` access to create issues! Unless there is a specific
+reason to do otherwise, you should only ever need to grant `read` access.
+
+The primary reason to grant `write` access is if your IssueOps flow uses pull
+requests instead of issues, but only if you want users to create pull requests
+from branches in the _same_ repository. As an alternative, you can allow forking
+of your repository and users can create pull requests from their forked
+repository instead.
+
+## Branch protection
+
+[Branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
+are a good idea regardless of what your repository is being used for! You should
+always protect your default branch (usually `main`) and any other branches that
+you want to prevent accidental changes to.
+
+For an IssueOps repository, you should create a branch protection rule for
+`main` that enables the following:
+
+- Require a pull request before merging
+- Require status checks to pass before merging (add any continuous integration
+  or testing workflows that you use)
+- Require branches to be up to date before merging
+- Require review from Code Owners (if your repository has a `CODEOWNERS` file)
+
+## GitHub Actions
+
+### Fork pull request workflows
+
+If your IssueOps workflow uses pull requests instead of issues, you must be
+careful about the configuration of GitHub Actions and what permissions are
+allowed for fork pull requests. The following settings can be enabled for fork
+pull requests, with a description of the risks involved.
+
+| Setting                                                         | Risk                                                            |
+| --------------------------------------------------------------- | --------------------------------------------------------------- |
+| Run workflows from fork pull requests                           | Forks will have read permissions to your repository             |
+| Send write tokens to workflows from fork pull requests          | Forks will have **write** permissions to your repository        |
+| Send secrets and variables to workflows from fork pull requests | Forks will have access to your secrets and variables            |
+| Require approval for fork pull request workflows                | Forks will not be able to run workflows until they are approved |
+
+As you can guess, the safest option is to not allow fork pull requests to run
+workflows at all. However, this may not be practical for your workflow. Here are
+some recommended settings:
+
+<DoDontContainer>
+  <Dont indented>Send write tokens to fork pull requests</Dont>
+  <Do indented>
+    Document required permissions for contributors to run the workflows
+    themselves
+  </Do>
+</DoDontContainer>
+
+<DoDontContainer>
+  <Dont indented>
+    Send secrets and variables to workflows from fork pull requests
+  </Dont>
+  <Do indented>
+    Document the required secrets and variables and how to generate them
+  </Do>
+</DoDontContainer>
+
+One alternative to consider is to "wrap" the creation of the PR into part of
+your IssueOps flow. If the content of the PR will follow a known format, you can
+use a GitHub Action to create the PR on behalf of the user. This will allow you
+to remove the need to allow any GitHub Actions access to fork pull requests. For
+an example of this scenario, see the
+[IssueOps Actions](/reference/issueops-actions) page.
+
+{/* TODO: Direct link to specific example */}
+
+### Workflow permissions
+
+In the repository settings, it is best to keep the base workflow permissions
+limited to _Read repository contents and packages permissions_. Within each
+IssueOps workflow, you can increase the permissions as needed for specific jobs.
+
+## Environments
+
+If your IssueOps workflow involves deployments or interaction with environments,
+you should consider adding enviroment-specific rules to restrict deployments to
+only the `main` branch. A common exception to this rule is if you are running
+IssueOps workflows from pull requests, as these will be run from branches other
+than `main`.
+
+This is also a good opportunity to further restrict access to secrets and
+variables by defining them at the environment level!