improving documentation

README.md

@@ -13,6 +13,7 @@ Goliac (Github Organization Leveraged by Infrastructure As Code), is a tool to m
 - [why Goliac](docs/why_goliac.md)
 - [Insallation guide](docs/installation.md)
 - [How to sync (users) from external](docs/installation.md#syncing-users-from-an-external-source)
+- [Troubleshooting guide](docs/troubleshooting.md)
 
 ## For regular users
 

docs/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting guide
+
+## How to resolve the error "more than X changesets to apply (total of Y), this is suspicious. Aborting"
+
+This error is happening if a changeset (a team's PR) introduce more than X changesets. This is a safety mechanism to avoid applying a huge number of changesets at once.
+
+If it is a legitimate change, you can
+- either create a new PR to reduce the number of changesets in the original PR to stay below the limit, Goliac will automatically apply the cumulative changesets.
+- or you can use the CLI to force apply the changesets. To do so, you can run the following command:
+
+```bash
+export GOLIAC_GITHUB_APP_ORGANIZATION=<your organization>
+export GOLIAC_GITHUB_APP_ID=<github app id>
+export GOLIAC_GITHUB_APP_PRIVATE_KEY_FILE=<github app private key filename>
+GOLIAC_MAX_CHANGESETS_OVERRIDE=true ./goliac apply <github teams url> <branch>
+```
+
+For example:
+
+```bash
+export GOLIAC_GITHUB_APP_ORGANIZATION=goliac-project
+export GOLIAC_GITHUB_APP_ID=123456
+export GOLIAC_GITHUB_APP_PRIVATE_KEY_FILE=github-app-private-key.pem
+GOLIAC_MAX_CHANGESETS_OVERRIDE=true ./goliac apply https://github.com/goliac-project/teams main
+```
+
+## How to bypass Goliac for a specific repository
+
+If you want to force merge a PR without Goliac validation, you will need to disable Golac for this specific repository temporarily.
+To do so, as a Gitbub admin, you can go to
+- the Github organization settings,
+- on the left menu, under `Code planning and automation` / `Repositories`, search for `Rulesets`
+- usually there is a `default` ruleset, click on it
+- then under `Target repositories`, you can search for the repository you want to bypass Goliac for, unselect it
+- then click on `Save changes` (at the bottom of the page)
+
+Note:
+- When Goliac will run (and its cache expires), it will put back the ruleset. Usually the cache is set to 86400 seconds (ie 1 day).
+- if you want to re-apply the ruleset quickly (when you have finished with your emergency chage), you can go to the Goliac UI and click on the `Flush cache` button, and then click on the `Re-Sync` button.

docs/why_goliac.md

@@ -1,9 +1,18 @@
 # Why Goliac
 
-Goliac is a tool to help you manage your Github Organization (repos/teams/users) in a friendly way
-- for your security team (enforcing some security rules globally, reducing the number of Github adminstrators, and passing compliance audits)
-- for your developpers (it is a developer self-serve tool)
-- without having to rely on your IT departement each time a team needs a new repository
+Goliac can improve your Github organization management in several ways:
+- cost
+- security
+- developer friendly
+
+## Cost
+
+Goliac is a free opensource project. You can install it on your own infrastructure, and it is designed to be run easily into a kubernetes environment.
+
+A comparable solution is to use Terraform (and a git repository) to achieve almost the same result, except that
+- if you are using Terraform Cloud, you will have to pay for each resource you manage
+- with terraform, you still need to centrally managed all operations via your IT team, which can be a bottleneck, and also less flexible
+
 
 ## Security friendly
 
@@ -12,13 +21,13 @@ Goliac allows your company to pass security compliance audit by:
 - allowing users to manage their team and the repositories they own (and only them)
 - bringing auditing of who has done what in 2 places:
   - via a git history of a git repository
-  - via logs of Goliac service
+  - via logs of Goliac service (but you need to have a good log management system in place)
 - via a [GitOps](https://www.redhat.com/en/topics/devops/what-is-gitops) approach: i.e. via a clear directory structure stored into a git repository
 
 ## Developer friendly
 
-Once a team of developer has been created, the team can
-- manage their resources (i.e. their team's member and their repositories defintion) autonomously
+Once a team of developers has been created, the team can
+- manage their resources (i.e. their team's member and their repositories defintion) autonomously (and so without having to rely on your IT departement each time a team needs a change)
 - via **simple** yaml files. You dont need to learn a new specific definition langage.
 - but restricted by global policies defined previously by the security team. For example you can specifiy a organization-wide policy asking for peer-review across all Github repositories, before any Pull Request being merged. Or you can ask a specific CI test to pass for all Github repositories, or a specific subset of Github repositoties
 

internal/github_batch_executor.go

@@ -213,7 +213,7 @@ func (g *GithubBatchExecutor) Rollback(dryrun bool, err error) {
 }
 func (g *GithubBatchExecutor) Commit(dryrun bool) error {
 	if len(g.commands) > g.maxChangesets && !config.Config.MaxChangesetsOverride {
-		return fmt.Errorf("more than %d changesets to apply (total of %d), this is suspicious. Aborting", g.maxChangesets, len(g.commands))
+		return fmt.Errorf("more than %d changesets to apply (total of %d), this is suspicious. Aborting (see Goliac troubleshooting guide for help)", g.maxChangesets, len(g.commands))
 	}
 	for _, c := range g.commands {
 		c.Apply()