diff --git a/README.md b/README.md index c8fef2e..33bf765 100644 --- a/README.md +++ b/README.md @@ -4,194 +4,247 @@ GitHappens demo -## Getting started 🚀 +## Getting Started 🚀 + +GitHappens is a Python CLI for GitLab workflows. It can create GitLab issues, +branches, and merge requests from templates, request reviewers, track time, +run AI review, show recent commit summaries, and inspect the last production +deployment. ## Installation 🔨 -### Preresequisits +### Prerequisites + +- Install Python 3 with pip. +- Install [glab](https://gitlab.com/gitlab-org/cli). +- Authorize glab with `glab auth login`. A GitLab access token is required; + SSH is recommended for repository access. +- Install 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 this repository to a local path that you plan to keep. The shell alias +points to this checkout, so moving or deleting it will break the command. + +Copy the example configuration files: + +```sh +cp configs/templates.json.example configs/templates.json +cp configs/config.ini.example configs/config.ini +``` + +In `configs/config.ini`, set at least: + +- `group_id`: GitLab group ID used for milestones, iterations, epics, and + labels. +- `GITLAB_TOKEN`: GitLab token used for API requests. -#### Setup configs +Optional settings include: -- 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). +- `developer_email`: filters `gh summary` output to commits by this email. +- `OPENAI_API_KEY`: enables AI summaries and AI code review. +- `incident_project_id`: target project for `gh report`. +- `squash_commits` and `delete_branch_after_merge`: merge request defaults. -#### Alias +Edit `configs/templates.json` to configure issue templates, reviewer IDs, and +production deployment mappings. The example file contains comments for +explanation, but JSON itself does not allow comments; remove comments before +using the file as `configs/templates.json`. -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'` +### Alias -Run `source ~/.zshrc` or restart terminal. +Add an alias to your shell config: + +```sh +alias gh='python3 /path/to/githappens/gitHappens.py' +``` + +Reload the matching shell config: + +```sh +source ~/.zshrc +``` + +Use `source ~/.bashrc` instead if you added the alias to Bash. ## Usage ⚡ -### Project selection +Run `gh` or `gh --help` to see available flags. + +### Create An Issue And Merge Request + +Pass the issue title as the command argument: -- 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 +```sh +gh "Implement account export" +``` + +GitHappens asks for a template, then creates the issue, branch, and merge +request unless the selected template or CLI flags request issue-only mode. -#### Issue creation for multiple projects at once +### Project Selection -This feature is useful if you have to create issue on both backend and frontend project for same thing. +Project selection is resolved in this order: -- You can specify list of ids in `templates.json` file. +1. `projectIds` from the selected template. +2. `--project_id=`. +3. The GitLab project detected from the current directory's `origin` remote. +4. An interactive project ID prompt. +Example: + +```sh +gh "Fix login redirect" --project_id=123456 ``` -... + +### Multiple Projects + +Use `projectIds` in a template when the same issue should be created across +multiple projects, such as backend and frontend repositories: + +```json { "name": "Feature issue for API and frontend", - ... + "labels": ["feature::Confirmed"], "projectIds": [123, 456] } -... ``` -### Milestone selection - -Milestone is set to current by default. If you want to pick it manually, pass `-m` or `--milestone` flag to the script. +### Templates -### Issue templates +Issue templates live in `configs/templates.json`. Template names must be unique. -Issue templates are located in `configs/templates.json`. +Common template keys: -**Make sure that names of templates are unique** +- `name`: template display name. +- `weight`: GitLab issue weight. +- `labels`: labels to apply. +- `projectIds`: one or more GitLab project IDs. +- `onlyIssue`: create only the issue. +- `type`: GitLab issue type, such as `issue` or `incident`. -### Excluding features +### Milestones, Iterations, And Epics -If you don't want to include some settings you use following flags: +By default, GitHappens selects the current milestone, prompts for an iteration, +and prompts for an epic. -- `--no_epic` - no epic will be selected or prompted -- `--no_milestone` - no milestone will be selected or prompted +Use these flags to change that behavior: -### Only issue +- `-m` or `--milestone`: choose the milestone manually. +- `--no_milestone`: skip milestone selection. +- `--no_iteration`: skip iteration selection. +- `--no_epic`: skip epic selection. -If you are in a hurry and want to create issue for later without merge request and branch this flag is for you. +### Issue-Only Mode -- `--only_issue` - no merge request nor branch will be created. - You can achive same functionality with adding onlyIssue key to `templates.json` file. +Use `--only_issue` when you do not want GitHappens to create a branch or merge +request: +```sh +gh "Write migration notes" --only_issue ``` -... + +You can also make this the default for a template: + +```json { "name": "Feature issue for later", - ... + "labels": ["feature::Confirmed"], "onlyIssue": true } -... ``` -### Open merge request in browser +### Open The Current Merge Request -You can open merge request for current checked out branch in browser with command: +Open the merge request for the current branch in your browser: -``` +```sh gh open ``` -### Git review +### Request Review -You can set default reviewers in templates.json file. +Set default reviewer IDs in `configs/templates.json`: -``` -... +```json { - "templates": [ - ... - ], - ... + "templates": [], "reviewers": [234, 456, 678] } -... ``` -To submit merge request into review run command: +Request review for the merge request on the current branch: -``` +```sh gh review ``` -To also enable **auto-merge when the pipeline succeeds**, add `--auto_merge` or `-am` flag: +Select reviewers manually: +```sh +gh review --select ``` -gh review –-auto_merge +Enable auto-merge when the pipeline succeeds: + +```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: +When `OPENAI_API_KEY` is configured, `gh review` also runs AI code review for +the branch diff and posts feedback to the merge request. -``` -gh review --select -``` +### AI Code Review -You will be prompted with an interactive list of reviewers to choose from. +Run AI code review locally without the rest of the review flow: +```sh +gh ai review +``` -### Last production deployment +### Commit Summaries -You can check when the last successful production deployment occurred: +Show recent commits from the last two weeks: -``` -gh last deploy +```sh +gh summary ``` -This command shows information about the most recent successful production deployment including timing, pipeline details, and how long ago it happened. +Generate an AI summary of those commits: -#### Configuration +```sh +gh summaryAI +``` -To configure production deployment detection, add project-specific mappings to your `templates.json`: +### Incident Reports -```json -{ - "templates": [...], - "reviewers": [...], - "productionMappings": { - "your_project_id": { - "stage": "production:deploy", - "job": "deploy-to-production" - }, - "another_project_id": { - "stage": "deploy", - "job": "production:deploy" - } - } -} +Create and close an incident issue, then add spent time: + +```sh +gh report "Short incident description" 30 ``` -**Note:** The command only considers deployments with "success" status to ensure accurate last deployment information. +Set `incident_project_id` in `configs/config.ini` before using this command. +### Last Production Deployment -You can check when the last successful production deployment occurred: +Show the most recent successful production deployment for the current project: -``` +```sh gh last deploy ``` -This command shows information about the most recent successful production deployment including timing, pipeline details, and how long ago it happened. - -#### Configuration - -To configure production deployment detection, add project-specific mappings to your `templates.json`: +Configure project-specific deployment detection in `configs/templates.json`: ```json { - "templates": [...], - "reviewers": [...], + "templates": [], + "reviewers": [], "productionMappings": { "your_project_id": { "stage": "production:deploy", @@ -205,24 +258,33 @@ 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. -### 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. +Only successful jobs are considered production deployments. ## Troubleshooting 🪲🔫 -### Recieving 401 Unauthorized error +### 401 Unauthorized + +If you get `glab: 401 Unauthorized (HTTP 401)`, run `glab auth login` again, +check `GITLAB_TOKEN` in `configs/config.ini`, and reopen your terminal. + +### Missing Config Files -If you get `glab: 401 Unauthorized (HTTP 401)` when using GitHappens, you must repeat `glab auth login` -and then reopen your terminal. +Make sure both local config files exist: + +```sh +ls configs/config.ini configs/templates.json +``` + +If either file is missing, copy it from the matching `.example` file and fill in +the required values. ## Contributing 🫂🫶 -Every contributor is welcome. -I suggest checking Gitlab's official API documentation: https://docs.gitlab.com/ee/api/merge_requests.html +Every contributor is welcome. GitLab's +[merge requests API documentation](https://docs.gitlab.com/ee/api/merge_requests.html) +is a useful reference. ## Donating 💜 -Make sure to check this project on [OpenPledge](https://app.openpledge.io/repositories/zigcBenx/gitHappens). - +Make sure to check this project on +[OpenPledge](https://app.openpledge.io/repositories/zigcBenx/gitHappens).