From edb5478536ad101abf245e93c52af9ef944c084a Mon Sep 17 00:00:00 2001 From: Nicolas Zin Date: Sat, 12 Oct 2024 02:44:18 -0400 Subject: [PATCH] improving documentation --- README.md | 1 + docs/troubleshooting.md | 39 +++++++++++++++++++++++++++++++ docs/why_goliac.md | 23 ++++++++++++------ internal/github_batch_executor.go | 2 +- 4 files changed, 57 insertions(+), 8 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index f506fe5..20dbe82 100644 --- a/README.md +++ b/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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..c7d64a2 --- /dev/null +++ b/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= +export GOLIAC_GITHUB_APP_ID= +export GOLIAC_GITHUB_APP_PRIVATE_KEY_FILE= +GOLIAC_MAX_CHANGESETS_OVERRIDE=true ./goliac apply +``` + +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. diff --git a/docs/why_goliac.md b/docs/why_goliac.md index 6269724..56f9a78 100644 --- a/docs/why_goliac.md +++ b/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 diff --git a/internal/github_batch_executor.go b/internal/github_batch_executor.go index 94ca960..7d416a0 100644 --- a/internal/github_batch_executor.go +++ b/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()