Skip to content

Commit 0d7f76c

Browse files
rjzondervanrjzondervan
authored
Merge pull request #10 from OpenCatalogi/feature/BEHEER-2273/document-github-index
Document sending updates to opencatalogi
2 parents 680ec73 + c588f70 commit 0d7f76c

1 file changed

Lines changed: 153 additions & 150 deletions

File tree

‎README.md‎

Lines changed: 153 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,153 @@
1-
# Publiccode Action
2-
This GitHub Action automatically generates and updates a `publiccode.yaml` file in the root of your repository, based on repository metadata. The file is updated each time a push is made to the main branch. It is basically a more advanced varsion of [the publiccode softwareversion check](https://github.com/italia/publiccode-softwareversion-check-action/tree/master)
3-
4-
The Action works by running a Python script that reads repository metadata such as the repository name and description, and uses this information to create or update the publiccode.yaml file.
5-
6-
## Usage
7-
To use this action, simply include it as a step in your workflow file. No inputs are required.
8-
9-
````yaml
10-
name: My PublicCode Workflow
11-
12-
permissions:
13-
contents: write
14-
15-
on:
16-
push:
17-
branches:
18-
- main
19-
20-
jobs:
21-
build:
22-
runs-on: ubuntu-latest
23-
steps:
24-
- name: Update publiccode.yaml
25-
uses: OpenCatalogi/publiccode-action@latest
26-
````
27-
28-
In the above example a `publiccode` file is updated every time code on the `main` branche is touched
29-
30-
> **Info**
31-
> Alternatively to setting the write permission for the workflow, you can also supply the action with an access token or an SSH key; see inputs for more details.
32-
33-
## Working with protected branches
34-
It is common (and good) practise to protect the main branche of a repository from direct file editing and only allowing this trough pull requests. This will however couse the action (and workflow containing it) to fail becouse the workflow won't have the rights to actually write or create the resulting publiccode or opencatalogi files to the repository.
35-
36-
The sollution here is two run the action two time's
37-
1- Once on the protected branche with the setting `save` set on false to prevent actual file creation or allteration
38-
2- Once on a branche where files may actually be added without a pull request (normally dev or development) setting `federlize` set on false to prevent unnececcery upates to the network
39-
40-
41-
## Inputs
42-
43-
| Input Name | Description | Default Value |
44-
|--------------|--------------------------------------------------------------|------------------------------------------|
45-
| `name` | Git URL of the remote repository to check (Optional) | {{ github.event.repository.name }} <br/> |
46-
| `description` | Git URL of the remote repository to check (Optional) | Empty String |
47-
| `remoterepo` | Git URL of the remote repository to check (Optional) | Empty String |
48-
| `publiccode` | `publiccode.yml` path (Optional), e.g. `data/publiccode.yml` | `publiccode.yml` |
49-
| `federlize` | Wheter to send an update event to the federilized open catalogi network | true |
50-
| `save` | Wheter to actually save the file to github | true |
51-
| `gitname` | Git name configuration for bump commit (Optional) | `Open Catalogi bot` |
52-
| `gitmail` | Git mail configuration for bump commit (Optional) | `bot@opencatalogi.nl` |
53-
54-
example ussage of the inputs
55-
56-
````yaml
57-
name: My PublicCode Workflow
58-
59-
permissions:
60-
contents: write
61-
62-
on:
63-
push:
64-
branches:
65-
- main
66-
67-
jobs:
68-
build:
69-
runs-on: ubuntu-latest
70-
steps:
71-
- name: Update publiccode.yaml
72-
uses: OpenCatalogi/publiccode-action@latest
73-
with:
74-
name: ${{ github.head_ref }} # Git URL of the remote repository to check
75-
description: ${{ github.head_ref }} # Git URL of the remote repository to check
76-
publiccode: docs/publiccode.yam # `publiccode.yml` path
77-
gitname: bot myorganisation # Git name configuration for bump commit
78-
gitmail: info@myorganisation.com # Git mail configuration for bump commit
79-
````
80-
81-
## Outputs
82-
The following outputs are provided by the action and can be used by other actions.
83-
84-
| Output Name | Description |
85-
|----------------|-------------------------------------------------|
86-
| `version` | New version of the `softwareVersion` field |
87-
| `releaseDate` | New release date of the `releaseDate` field |
88-
89-
90-
## Example
91-
To use this action, simply include it as a step in your workflow file. No inputs are required.
92-
93-
````yaml
94-
steps:
95-
- name: Update publiccode.yaml
96-
uses: OpenCatalogi/publiccode-action@latest
97-
with:
98-
name: "My Codebase"
99-
description: "This is a sample repository description"
100-
publiccode: "publiccode.yml"
101-
gitname: "Open Catalogi bot"
102-
gitmail: "bot@opencatalogi.nl"
103-
````
104-
Note: Replace `your-github-username` with your actual GitHub username, and `publiccode-update-action` with the name of the repository where this action is hosted.
105-
106-
## Tips
107-
Need a quick way to present your project online but don't have the time te create a dedicated website? Combine the publiccode code actions with the product page action to get an instant website for you project.
108-
109-
````yaml
110-
name: My PublicCode Workflow
111-
112-
permissions:
113-
contents: write
114-
115-
on:
116-
push:
117-
branches:
118-
- main
119-
120-
jobs:
121-
build:
122-
runs-on: ubuntu-latest
123-
steps:
124-
- name: Update publiccode.yaml
125-
uses: OpenCatalogi/publiccode-action@latest
126-
- name: Deploy Product Github Page
127-
uses: OpenCatalogi/productpage-action@latest
128-
````
129-
130-
[Read more](https://github.com/marketplace/actions/create-an-product-page) about the product page action
131-
132-
## Architecture
133-
### Why Python?
134-
Python is natively supported by GitHub actions' underlaying containers and therefore very quick
135-
136-
### Asumptions
137-
We follow the "get data from the source" principle, in practice for this action that means that we set the repository as the source. So any settings in the repository (e.g. name and description) will overwrite the values already pressent in your publiccode.
138-
139-
Please note that this action does not handle errors or exceptions while reading metadata or writing to publiccode.yaml. You should ensure that your repository is properly set up to avoid any issues. For example, make sure that your repository name and description are not empty.
140-
141-
## Maintainers
142-
This software is maintained by [Conduction b.v.](https://conduction.nl/)
143-
144-
## License
145-
© 2023 Conduction B.V.
146-
147-
Licensed under the EUPL. The version control system provides attribution for specific lines of code.
148-
149-
## Remarks
150-
This GitHub Action is published in the GitHub Marketplace. As such, you can find the [Terms of Service here](). Also, [here]() you can find the GitHub Marketplace Developer Agreement.
1+
# Publiccode Action
2+
This GitHub Action automatically generates and updates a `publiccode.yaml` file in the root of your repository, based on repository metadata. The file is updated each time a push is made to the main branch. It is basically a more advanced varsion of [the publiccode softwareversion check](https://github.com/italia/publiccode-softwareversion-check-action/tree/master)
3+
4+
The Action works by running a Python script that reads repository metadata such as the repository name and description, and uses this information to create or update the publiccode.yaml file.
5+
6+
## Usage
7+
To use this action, simply include it as a step in your workflow file. No inputs are required.
8+
9+
````yaml
10+
name: My PublicCode Workflow
11+
12+
permissions:
13+
contents: write
14+
15+
on:
16+
push:
17+
branches:
18+
- main
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Update publiccode.yaml
25+
uses: OpenCatalogi/publiccode-action@latest
26+
````
27+
28+
In the above example a `publiccode` file is updated every time code on the `main` branche is touched
29+
30+
> **Info**
31+
> Alternatively to setting the write permission for the workflow, you can also supply the action with an access token or an SSH key; see inputs for more details.
32+
33+
### Sending event to OpenCatalogi
34+
This action also automatically sends an update message to the OpenCatalogi-API, so that the publiccode is reloaded by OpenCatalogi. However, the repository has to be indexed by GitHub for this to work properly the first time. This can be done by performing a search on the GitHub website in the repository, for example by searching `repo:{{your org/user}}/{{your repo}} publiccode` in the search bar on the GitHub website. This might take 10-15 minutes and several refreshes of the GitHub website.
35+
36+
## Working with protected branches
37+
It is common (and good) practise to protect the main branche of a repository from direct file editing and only allowing this trough pull requests. This will however couse the action (and workflow containing it) to fail becouse the workflow won't have the rights to actually write or create the resulting publiccode or opencatalogi files to the repository.
38+
39+
The sollution here is two run the action two time's
40+
1- Once on the protected branche with the setting `save` set on false to prevent actual file creation or allteration
41+
2- Once on a branche where files may actually be added without a pull request (normally dev or development) setting `federlize` set on false to prevent unnececcery upates to the network
42+
43+
44+
## Inputs
45+
46+
| Input Name | Description | Default Value |
47+
|--------------|--------------------------------------------------------------|------------------------------------------|
48+
| `name` | Git URL of the remote repository to check (Optional) | {{ github.event.repository.name }} <br/> |
49+
| `description` | Git URL of the remote repository to check (Optional) | Empty String |
50+
| `remoterepo` | Git URL of the remote repository to check (Optional) | Empty String |
51+
| `publiccode` | `publiccode.yml` path (Optional), e.g. `data/publiccode.yml` | `publiccode.yml` |
52+
| `federlize` | Wheter to send an update event to the federilized open catalogi network | true |
53+
| `save` | Wheter to actually save the file to github | true |
54+
| `gitname` | Git name configuration for bump commit (Optional) | `Open Catalogi bot` |
55+
| `gitmail` | Git mail configuration for bump commit (Optional) | `bot@opencatalogi.nl` |
56+
57+
example ussage of the inputs
58+
59+
````yaml
60+
name: My PublicCode Workflow
61+
62+
permissions:
63+
contents: write
64+
65+
on:
66+
push:
67+
branches:
68+
- main
69+
70+
jobs:
71+
build:
72+
runs-on: ubuntu-latest
73+
steps:
74+
- name: Update publiccode.yaml
75+
uses: OpenCatalogi/publiccode-action@latest
76+
with:
77+
name: ${{ github.head_ref }} # Git URL of the remote repository to check
78+
description: ${{ github.head_ref }} # Git URL of the remote repository to check
79+
publiccode: docs/publiccode.yam # `publiccode.yml` path
80+
gitname: bot myorganisation # Git name configuration for bump commit
81+
gitmail: info@myorganisation.com # Git mail configuration for bump commit
82+
````
83+
84+
## Outputs
85+
The following outputs are provided by the action and can be used by other actions.
86+
87+
| Output Name | Description |
88+
|----------------|-------------------------------------------------|
89+
| `version` | New version of the `softwareVersion` field |
90+
| `releaseDate` | New release date of the `releaseDate` field |
91+
92+
93+
## Example
94+
To use this action, simply include it as a step in your workflow file. No inputs are required.
95+
96+
````yaml
97+
steps:
98+
- name: Update publiccode.yaml
99+
uses: OpenCatalogi/publiccode-action@latest
100+
with:
101+
name: "My Codebase"
102+
description: "This is a sample repository description"
103+
publiccode: "publiccode.yml"
104+
gitname: "Open Catalogi bot"
105+
gitmail: "bot@opencatalogi.nl"
106+
````
107+
Note: Replace `your-github-username` with your actual GitHub username, and `publiccode-update-action` with the name of the repository where this action is hosted.
108+
109+
## Tips
110+
Need a quick way to present your project online but don't have the time te create a dedicated website? Combine the publiccode code actions with the product page action to get an instant website for you project.
111+
112+
````yaml
113+
name: My PublicCode Workflow
114+
115+
permissions:
116+
contents: write
117+
118+
on:
119+
push:
120+
branches:
121+
- main
122+
123+
jobs:
124+
build:
125+
runs-on: ubuntu-latest
126+
steps:
127+
- name: Update publiccode.yaml
128+
uses: OpenCatalogi/publiccode-action@latest
129+
- name: Deploy Product Github Page
130+
uses: OpenCatalogi/productpage-action@latest
131+
````
132+
133+
[Read more](https://github.com/marketplace/actions/create-an-product-page) about the product page action
134+
135+
## Architecture
136+
### Why Python?
137+
Python is natively supported by GitHub actions' underlaying containers and therefore very quick
138+
139+
### Asumptions
140+
We follow the "get data from the source" principle, in practice for this action that means that we set the repository as the source. So any settings in the repository (e.g. name and description) will overwrite the values already pressent in your publiccode.
141+
142+
Please note that this action does not handle errors or exceptions while reading metadata or writing to publiccode.yaml. You should ensure that your repository is properly set up to avoid any issues. For example, make sure that your repository name and description are not empty.
143+
144+
## Maintainers
145+
This software is maintained by [Conduction b.v.](https://conduction.nl/)
146+
147+
## License
148+
© 2023 Conduction B.V.
149+
150+
Licensed under the EUPL. The version control system provides attribution for specific lines of code.
151+
152+
## Remarks
153+
This GitHub Action is published in the GitHub Marketplace. As such, you can find the [Terms of Service here](). Also, [here]() you can find the GitHub Marketplace Developer Agreement.

0 commit comments

Comments
 (0)