Skip to content
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

Jump to bottom

Improvements to overall architecture. Documentation clarity #1

Merged
merged 3 commits into from
Aug 9, 2023
Merged

Improvements to overall architecture. Documentation clarity #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
323e02c
fix: prevent early commit before repo exists
keiranlovett Aug 4, 2023
68b687c
feat: split logic into modules based on event type
keiranlovett Aug 4, 2023
7cca1b6
doc: reorganize documentation + include new details on config
keiranlovett Aug 4, 2023
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
121 changes: 72 additions & 49 deletions Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,17 @@ Currently supported:

This is achieved by using Gitlabs "System Hooks" (not to be confused with server hooks or file hooks) that perform `HTTP POST` requests and are triggered by various Gitlab system events. You can see a complete list on Gitlabs [System Hooks page](https://docs.gitlab.com/ee/administration/system_hooks.html).

#### To create a system hook:

> You must have Administrative access to the Gitlab instance you wish to configure the System Hook.

1. Open the intended Gitlab instance you want to trigger events on.
2. On the left sidebar, expand the top-most chevron.
3. Select **Admin Area**.
4. On the left sidebar, select **System Hooks**.
5. Provide the **URL** and **Secret Token**.
6. Select the checkbox next to each optional **Trigger** you want to enable.
7. Select **Enable SSL verification**, if desired.
8. Select **Add system hook**.

> You can easily debug your system hook receiver by going to **Admin Area -> System Hooks > Edit**, On the bottom of the screen there are “**Recent Deliveries**”. You can go to “View details” on each one of the requests in order to get additional debugging information— you can check the “Request headers” & “Response headers” of your request, the “Response body” that came back from your receiver and the JSON itself.
## Configuration

## Environment Variables
### Environment Variables
Before running the webhook, you need to set the following environment variables:
* `GITLAB_URL`: Required. The URL of your Gitlab instance (e.g., https://your.gitlab.domain).
* `GITLAB_ACCESS_TOKEN`: Required. Gitlab access token with admin privileges.
* `GITLAB_DEFAULT_BRANCH`: Optional. The default branch to use when creating commits (e.g., "main" or "master"). (Default value: `Main`)
* `CONFIG_FILE_PATH`: Optional. The path to the configuration file (`config.yml`) that defines the injection rules for new projects. (Default value: `'config.yml'`)
* `LISTEN_PORT`: Optional: The port on which the webhook will listen for incoming requests. (Default value: `3002`)

## Configuration
### `Config.yaml`
The config.yml file defines the injection rules for new projects. It consists of an array of objects, each representing a specific rule for project injection. Below is an explanation of the properties used in the configuration:

#### `regex` (required)
Expand Down Expand Up @@ -65,6 +52,8 @@ For example, to add two groups with different access levels to a project:
access: 30
# Rest of the properties...
```
#### `commits`
Commit files that you'd like to be injected into the project. You then define the `message` and `paths` for that commit.

#### `message` (optional)
This property defines the default commit message that will be used when creating commits for new projects. If not specified, a default placeholder commit message will be used. For example:
Expand All @@ -78,56 +67,92 @@ This property defines the default commit message that will be used when creating
This property specifies the files to be injected into the project. It should be an array of objects, where each object has a **source** and a **target** property. The **source** property specifies the path to the file that will be injected, and the **target** property specifies the path where the file will be placed in the new project. For example:
```yaml
- regex: "example-project"
paths:
- source: "includes/.gitignore"
target: ".gitignore"
- source: "includes/README.md"
target: "README.md"
commit:
paths:
- source: "includes/.gitignore"
target: ".gitignore"
- source: "includes/README.md"
target: "README.md"
# Rest of the properties...
```

### Complete Example `config.yml`

#### Complete Example `config.yml`
```yaml
- regex: "^documentation/"
groups:
- name: managers
access: 30
- name: developers
access: 10
message: "This is a commit for documentation repositories..."
paths: []
commit:
message: "This is a commit for documentation repositories..."
paths: []

- regex: "^game/"
groups:
- name: managers
access: 30
message: "This is a commit for games repositories..."
paths:
- source: "includes/games/.gitignore"
target: ".gitignore"
commit:
message: "This is a commit for games repositories..."
paths:
- source: "includes/games/.gitignore"
target: ".gitignore"

- regex: ".*" # Default regex
message: "This is a commit for default repositories..."
paths:
- source: "includes/default/.gitignore"
target: ".gitignore"
- source: "includes/default/.gitlab-ci.yml"
target: ".gitlab-ci.yml"
- source: "includes/default/README.md"
target: "README.md"
commit:
message: "This is a commit for default repositories..."
paths:
- source: "includes/default/.gitignore"
target: ".gitignore"
- source: "includes/default/.gitlab-ci.yml"
target: ".gitlab-ci.yml"
- source: "includes/default/README.md"
target: "README.md"
```

### GitLab API Tokens
Go to profile/personal_access_tokens on your GitLab instance.
## Usage

### Endpoints
| Endpoint | Type | Purpose |
|---------- |------ |-------------------------------------------------- |
| / | POST | Verfiy the server is working |
| /hook | GET | Trigger the action on server |
| /config | POST | Get a printout of the current configuration yaml |

### Gitlab Instance

To create a Personal Access Token, give it a name, and check the api box under Scopes.
Then click the Create personal access token button.
#### GitLab API Tokens
To authorise the hook within Gitlabs API's, you need to pass a Personal Access Tokens.

1. Open the intended Gitlab instance you want to trigger events on.
2. Log in with the intended account you wish to generate the Personal Access Tokens for.
3. Select **Profile**.
4. On the left sidebar, select **Personal Access Tokens**.
5. Provide the **Name**.
6. Select the checkbox next to each optional **Scope** you want to enable.
3. Click the **Create** personal access token button.

> Note: You may want to do this step with a unique account that doesn't belong to an actual user. This prevents problems if the token holder's user leaves your org and their account has to be deleted.

#### To create a system hook:
> You must have Administrative access to the Gitlab instance you wish to configure the System Hook.

The **URL** should be: `yourdomain.tld/hook/`

## Usage with Docker
1. Open the intended Gitlab instance you want to trigger events on.
2. On the left sidebar, expand the top-most chevron.
3. Select **Admin Area**.
4. On the left sidebar, select **System Hooks**.
5. Provide the **URL** and **Secret Token**.
6. Select the checkbox next to each optional **Trigger** you want to enable.
7. Select **Enable SSL verification**, if desired.
8. Select **Add system hook**.

> You can easily debug your system hook receiver by going to **Admin Area -> System Hooks > Edit**, On the bottom of the screen there are “**Recent Deliveries**”. You can go to “View details” on each one of the requests in order to get additional debugging information— you can check the “Request headers” & “Response headers” of your request, the “Response body” that came back from your receiver and the JSON itself.

### Docker

#### Usage with Docker
If you prefer to run the webhook in a Docker container, you can use the following command:

```bash
Expand All @@ -143,7 +168,7 @@ docker run -d \
ghcr.io/keiranlovett/gitlab-server-hook:main
```

## Usage without Docker
#### Usage without Docker
If you want to run the webhook without Docker, follow these steps:

1. Make sure you have [Node.js](https://nodejs.org) installed.
Expand All @@ -153,11 +178,9 @@ If you want to run the webhook without Docker, follow these steps:
5. Add a system hook in Gitlab that points to the webhook's URL to receive project creation events.
6. Create a new project in Gitlab, and it will automatically be shared with the specified default group.



# TODO / Contributing

- [] Support for adding specific `Members` to a project.
- [] Enfore a project naming convention.
- [] Custom logging support???
- Pulling or changing data in LDAP servers.
- [ ] Support for adding specific `Members` to a project.
- [ ] Enforce a project naming convention.
- [ ] Custom logging support???
- [ ] Pulling or changing data in LDAP servers.
Loading
Loading