Skip to content

Fix README docs #144

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
XDiamond7D7 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix README docs #144

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
147 changes: 78 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,53 +4,62 @@
<img src="https://github.com/user-attachments/assets/f18c0f04-edef-467c-b833-019643642beb" alt="GitHappens demo" />
</div>

## 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 ~/<path-to-githappens-project>/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 ~/<path-to-githappens-project>/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",
Expand All @@ -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",
Expand All @@ -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": [
Expand All @@ -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
```

Expand Down Expand Up @@ -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).