diff --git a/README.md b/README.md index c8fef2e..be690d7 100644 --- a/README.md +++ b/README.md @@ -4,53 +4,62 @@ GitHappens demo -## Getting started 🚀 - ## Installation 🔨 -### Preresequisits +### Prerequisites + +- Install Python 3 and make sure pip is included. +- Install [glab](https://gitlab.com/gitlab-org/cli). +- Authorize glab with `glab auth login`. You will need a GitLab access token; SSH is recommended. +- Install the Python dependencies: -- install python3 (make sure to include pip in install) -- Install [glab](https://gitlab.com/gitlab-org/cli) -- Authorize via glab `glab auth login` (you will need Gitlab access token, SSH recomended) -- `pip install inquirer` or `pip3 install inquirer` -- `pip install requests` or `pip3 install requests` +```sh +pip install -r requirements.txt +``` ### Setup -- Clone repository to your local machine to whatever destination you want (just don't delete it later) +- Clone the repository to your local machine in a location you will keep. #### Setup configs -- In configs folder copy example files like so: - `cp configs/templates.json.example configs/templates.json` - `cp configs/config.ini.example configs/config.ini` -- In `configs.ini` you have to paste id of your group in Gitlab to `group_id` (This is for fetching milestones and epics) -- You can adjust templates now, or play with them later (however, you have to remove comments from json before running the command). +- In the `configs` folder, copy the example files: + +```sh +cp configs/templates.json.example configs/templates.json +cp configs/config.ini.example configs/config.ini +``` + +- In `config.ini`, set your GitLab group ID as `group_id`. This is used for fetching milestones, iterations, labels, and epics. +- In `config.ini`, set `GITLAB_TOKEN` to a GitLab token with access to the projects you want to manage. +- You can adjust templates now or later. If you edit `templates.json`, remove comments before running the command because JSON does not support comments. #### Alias -To run gitHappens script anywhere in filesystem, make sure to create an alias. -Add following line to your `.bashrc` or `.zshrc` file -`alias gh='python3 ~//gitHappens.py'` +To run the GitHappens script anywhere in the filesystem, create an alias. +Add the following line to your `.bashrc` or `.zshrc` file: -Run `source ~/.zshrc` or restart terminal. +```sh +alias gh='python3 ~//gitHappens.py' +``` + +Run `source ~/.zshrc` or restart your terminal. ## Usage ⚡ ### Project selection -- Project selection is made automatically if you run script in same path as your project is located. -- You can specify project id or URL-encoded path as script argument e.g.: `--project_id=123456` -- If no of steps above happen, program will prompt you with question about project_id +- Project selection is automatic if you run the script from inside a GitLab project checkout. +- You can specify a project ID or URL-encoded path with `--project_id=123456`. +- If neither of the above applies, the program prompts you for `project_id`. #### Issue creation for multiple projects at once -This feature is useful if you have to create issue on both backend and frontend project for same thing. +This feature is useful when you have to create the same issue on both backend and frontend projects. -- You can specify list of ids in `templates.json` file. +- You can specify a list of IDs in `templates.json`. -``` +```json ... { "name": "Feature issue for API and frontend", @@ -62,29 +71,30 @@ This feature is useful if you have to create issue on both backend and frontend ### Milestone selection -Milestone is set to current by default. If you want to pick it manually, pass `-m` or `--milestone` flag to the script. +Milestone is set to current by default. If you want to pick it manually, pass the `-m` or `--milestone` flag. ### Issue templates Issue templates are located in `configs/templates.json`. -**Make sure that names of templates are unique** +**Make sure template names are unique.** ### Excluding features -If you don't want to include some settings you use following flags: +If you do not want to include some settings, use the following flags: - `--no_epic` - no epic will be selected or prompted - `--no_milestone` - no milestone will be selected or prompted +- `--no_iteration` - no iteration will be selected or prompted ### Only issue -If you are in a hurry and want to create issue for later without merge request and branch this flag is for you. +If you are in a hurry and want to create an issue for later without a merge request and branch, use this flag. - `--only_issue` - no merge request nor branch will be created. - You can achive same functionality with adding onlyIssue key to `templates.json` file. + You can achieve the same functionality by adding the `onlyIssue` key to `templates.json`. -``` +```json ... { "name": "Feature issue for later", @@ -96,17 +106,17 @@ If you are in a hurry and want to create issue for later without merge request a ### Open merge request in browser -You can open merge request for current checked out branch in browser with command: +You can open the merge request for the currently checked-out branch in your browser: -``` +```sh gh open ``` ### Git review -You can set default reviewers in templates.json file. +You can set default reviewers in `templates.json`. -``` +```json ... { "templates": [ @@ -118,35 +128,49 @@ You can set default reviewers in templates.json file. ... ``` -To submit merge request into review run command: +To submit a merge request into review, run: -``` +```sh gh review ``` -To also enable **auto-merge when the pipeline succeeds**, add `--auto_merge` or `-am` flag: +To also enable **auto-merge when the pipeline succeeds**, add the `--auto_merge` or `-am` flag: -``` -gh review –-auto_merge +```sh +gh review --auto_merge gh review -am ``` + ### Manually selecting reviewers To manually select reviewers for your merge request, use the `--select` flag with the review command: -``` +```sh gh review --select ``` You will be prompted with an interactive list of reviewers to choose from. +### Commit summary + +You can print commits from the last two weeks: + +```sh +gh summary +``` + +If `OPENAI_API_KEY` is configured in `config.ini` and the `openai` Python package is installed, you can generate an AI summary: + +```sh +gh summaryAI +``` ### Last production deployment You can check when the last successful production deployment occurred: -``` +```sh gh last deploy ``` @@ -175,54 +199,39 @@ To configure production deployment detection, add project-specific mappings to y **Note:** The command only considers deployments with "success" status to ensure accurate last deployment information. +### Incident report -You can check when the last successful production deployment occurred: +You can create and immediately close an incident issue with time tracking: -``` -gh last deploy +```sh +gh report "Incident title" 30 ``` -This command shows information about the most recent successful production deployment including timing, pipeline details, and how long ago it happened. +Configure `incident_project_id` in `config.ini` before using this command. -#### Configuration +### AI code review -To configure production deployment detection, add project-specific mappings to your `templates.json`: +You can run an AI code review for the current repository: -```json -{ - "templates": [...], - "reviewers": [...], - "productionMappings": { - "your_project_id": { - "stage": "production:deploy", - "job": "deploy-to-production" - }, - "another_project_id": { - "stage": "deploy", - "job": "production:deploy" - } - } -} +```sh +gh ai review ``` -**Note:** The command only considers deployments with "success" status to ensure accurate last deployment information. ### Flag help -If you run just `gh` (or whatever alias you set) or `gh --help` you will see all available flags and a short explanation. +If you run just `gh` (or whatever alias you set) or `gh --help`, you will see all available flags and a short explanation. ## Troubleshooting 🪲🔫 -### Recieving 401 Unauthorized error +### Receiving 401 Unauthorized error -If you get `glab: 401 Unauthorized (HTTP 401)` when using GitHappens, you must repeat `glab auth login` -and then reopen your terminal. +If you get `glab: 401 Unauthorized (HTTP 401)` when using GitHappens, repeat `glab auth login` and then reopen your terminal. ## Contributing 🫂🫶 Every contributor is welcome. -I suggest checking Gitlab's official API documentation: https://docs.gitlab.com/ee/api/merge_requests.html +I suggest checking GitLab's official API documentation: https://docs.gitlab.com/ee/api/merge_requests.html ## Donating 💜 Make sure to check this project on [OpenPledge](https://app.openpledge.io/repositories/zigcBenx/gitHappens). -