Plugin rights

Plugins are the true power of GitRoot. But, as you know, with power comes responsability. To be sure to understand what a plugin can and can’t, GitRoot expose all details in .gitroot/plugins.yml.

First example

Taking ladybug as an example:

 1- purl: pkg:gitroot/gitroot/ladybug@0.0.5?checksum=sha256:7409837469ce89d5c9fd8dd48236764650f4852&registry=https:%2F%2F%2Fgitroot.dev%2Freleases%2F0.5.0
 2  active: true
 3  run:
 4    - path: issues/**/*.md
 5      branch:
 6        - "*"
 7      when:
 8        - add
 9        - mod
10      write:
11        git:
12          - path: issues/**/*.md
13            can:
14              - mod
15        web: []
16      configuration: ...

You can read: “for all branches in your repository, when you modify or create any markdown file in the directory or a sud-directory of issues execute the plugin. During execution it can write in any markdown file in the directory or a sud-directory of issues in modification.”

But it can’t create a file in git or write in web.

Be carrefull, the plugin will be called for modification of issues/1.md, but it can modify issues/2.md if it need to do.

Configuration has been omitted because it depend on each plugin.

More complexe example

If you look at the plugins.yml of GitRoot itself you will see that apex plugin have a more complexe configuration:

 1- purl: pkg:gitroot/gitroot/apex@0.0.5?checksum=sha256:97fa5fd2b49f7c9d0b9b6b&registry=https:%2F%2F%2Fgitroot.dev%2Freleases%2F0.5.0
 2  active: true
 3  run:
 4    - path: "**/*"
 5      branch:
 6        - main
 7      when:
 8        - add
 9        - mod
10        - del
11      write:
12        git:
13          - path: index.md
14            can:
15              - add
16        web:
17          - path: "**/*"
18            can:
19              - add
20              - mod
21              - del
22              - append
23      configuration: &apexConf
24        header: ...
25    - path: "**/*"
26      branch:
27        - "*"
28        - "!main"
29      when:
30        - add
31        - mod
32        - del
33      write:
34        git: []
35        web:
36          - path: branches/**/*
37            can:
38              - add
39              - mod
40              - del
41              - append
42      configuration:
43        <<: *apexConf
44        generateGitWorktree: false

You can read it as: “On the main branch, every file can be rendered in the web. An index.md can be created in the git worktree. But for all other branches, apex plugin can only write in the branches directory”.

Why? Because in GitRoot everybody can create a branch. Imagine if a bad person come, create a branch and delete all the content of the repository. Then push it, if apex render that in the web, your repository website will be empty… What we want is: render modif in an other url (e.g. http://myTld.com/myRepo/branches/brach-test/myFile) and when the change are commited to the default branche render in final destination (e.g. http://myTld.com/myRepo/myFile).