Skip to content

docs: clean up README usage guide #155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
subhajitlucky wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: clean up README usage guide #155

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
284 changes: 173 additions & 111 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,194 +4,247 @@
<img src="https://github.com/user-attachments/assets/f18c0f04-edef-467c-b833-019643642beb" alt="GitHappens demo" />
</div>

## 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.
Comment on lines +20 to +21
- 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 ~/<path-to-githappens-project>/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=<id-or-url-encoded-path>`.
3. The GitLab project detected from the current directory's `origin` remote.
4. An interactive project ID prompt.

Comment on lines +96 to 97
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",
Expand All @@ -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.

Comment on lines +265 to +269
### 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).
Loading