Skip to content

Commit 22d180f

Browse files
atrisovicatrisovic
committed
add docs and set publish to false
closes #6
1 parent 88c38e4 commit 22d180f

File tree

4 files changed

+69
-58
lines changed

4 files changed

+69
-58
lines changed

‎CITATION.cff‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
## Testing locally
22

3-
To test your contribution locally run the Python script in the following format:
3+
To test your contribution locally from the command line, run the Python script in the following format:
4+
45
```
56
python dataverse.py DATAVERSE_TOKEN DATAVERSE_SERVER DATASET_DOI REPO_NAME
67
```

‎README.md‎

Lines changed: 66 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,29 @@
11
# Dataverse Uploader
22

3-
This action uploads the repository content to a Dataverse dataset.
3+
This action automatically uploads GitHub repository content to a Dataverse dataset.
4+
It can upload the entire repository or its subdirectory into an existing dataset on a target
5+
Dataverse installation. The action is customizable, allowing you to fully replace a dataset,
6+
add to the dataset, publish it or leave it as a draft version on Dataverse.
7+
8+
The action provides some additional metadata to the dataset, such as the origin GitHub repository,
9+
and it preserves the directory tree structure.
410

511
## Input parameters
612

713
To use this action, you will need the following input parameters:
814

9-
| Parameter | Required | Description |
10-
| --------- | -------- | ------------|
15+
| Parameter | Required | Description |
16+
| --------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1117
| `DATAVERSE_TOKEN` | **Yes** | This is your personal access token that you can create at your Dataverse instance (see [the Dataverse guide](https://guides.dataverse.org/en/latest/user/account.html#how-to-create-your-api-token)). Save your token as a secret variable called `DATAVERSE_TOKEN` in your GitHub repository that you want to upload to Dataverse (see [the GitHub guide](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository)). |
12-
| `DATAVERSE_SERVER` | **Yes** | The URL of your Dataverse installation, i.e., [https://dataverse.harvard.edu](https://dataverse.harvard.edu). |
13-
| `DATAVERSE_DATASET_DOI` | **Yes** | This action requires that a dataset (with a DOI) exists on the Dataverse server. Make sure to specify your DOI in this format: `doi:<doi>`, i.e., `doi:10.70122/FK2/LVUA`. |
14-
| `GITHUB_DIR` | No | Use `GITHUB_DIR` if you would like to upload files from only a specific subdirectory in your GitHub repository (i.e., just `data/`). |
15-
| `DELETE` | No | Can be `True` or `False` (by default `True`) depending on whether all files should be deleted in the dataset on Dataverse before upload. |
16-
| `PUBLISH` | No | Can be `True` or `False` (by default `True`) depending on whether you'd like to automatically create a new version of the dataset upon upload. If `False`, the uploaded dataset will be a `DRAFT`. |
18+
| `DATAVERSE_SERVER` | **Yes** | The URL of your Dataverse installation, i.e., [https://dataverse.harvard.edu](https://dataverse.harvard.edu). |
19+
| `DATAVERSE_DATASET_DOI` | **Yes** | This action requires that a dataset (with a DOI) exists on the Dataverse server. Make sure to specify your DOI in this format: `doi:<doi>`, i.e., `doi:10.70122/FK2/LVUA`. |
20+
| `GITHUB_DIR` | No | Use `GITHUB_DIR` if you would like to upload files from only a specific subdirectory in your GitHub repository (i.e., just `data/`). |
21+
| `DELETE` | No | Can be `True` or `False` (by default `True`) depending on whether all files should be deleted in the dataset on Dataverse before upload. |
22+
| `PUBLISH` | No | Can be `True` or `False` (by default `False`) depending on whether you'd like to automatically create a new version of the dataset upon upload. If `False`, the uploaded dataset will be a `DRAFT`. |
1723

1824
## Usage
1925

20-
To use the action, create a new YML file (i.e., `workflow.yml`) in the directory `.github/workflows/` in your GitHub repository.
26+
To use the action, create a new YML file (i.e., `workflow.yml`) and place it in the directory `.github/workflows/` in your GitHub repository.
2127

2228
The action workflow can be executed at trigger events such as `push` and `release`. If you'd only like to run the workflow manually from the Actions tab, use the `workflow_dispatch` event option.
2329

@@ -33,64 +39,71 @@ jobs:
3339
runs-on: ubuntu-latest
3440
steps:
3541
- name: Send repo to Dataverse
36-
uses: IQSS/dataverse-uploader@v1.1
42+
uses: IQSS/dataverse-uploader@v1.2
3743
with:
3844
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
3945
DATAVERSE_SERVER: https://demo.dataverse.org
4046
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
4147
```
4248

43-
If you'd like to upload files from a specific subdirectory only, you should add the `GITHUB_DIR` argument in your workflow.
49+
If you'd like to upload files from a specific subdirectory only (for instance, a `data` folder),
50+
you should add the `GITHUB_DIR` argument in your workflow, as follows:
4451

4552
```
46-
jobs:
47-
build:
48-
runs-on: ubuntu-latest
49-
steps:
50-
- name: Send repo to Dataverse
51-
uses: IQSS/dataverse-uploader@v1.1
52-
with:
53-
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
54-
DATAVERSE_SERVER: https://demo.dataverse.org
55-
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
56-
GITHUB_DIR: data
53+
steps:
54+
- name: Send repo to Dataverse
55+
uses: IQSS/dataverse-uploader@v1.2
56+
with:
57+
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
58+
DATAVERSE_SERVER: https://demo.dataverse.org
59+
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
60+
GITHUB_DIR: data
5761
```
5862

59-
If you wouldn't want the action to delete your dataset before upload (i.e., if you already have a Dataverse `DRAFT` dataset), set the `DELETE` argument to `False` like:
63+
By default, the action will sync the GitHub repository and the Dataverse dataset, meaning that it will
64+
delete the Dataverse content before uploading the content from GitHub. If you don't want the action to
65+
delete your dataset before upload (i.e., if you already have a Dataverse `DRAFT` dataset),
66+
set the `DELETE` argument to `False` like:
6067

6168
```
62-
jobs:
63-
build:
64-
runs-on: ubuntu-latest
65-
steps:
66-
- name: Send repo to Dataverse
67-
uses: IQSS/dataverse-uploader@v1.1
68-
with:
69-
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
70-
DATAVERSE_SERVER: https://demo.dataverse.org
71-
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
72-
GITHUB_DIR: data
73-
DELETE: False
69+
steps:
70+
- name: Send repo to Dataverse
71+
uses: IQSS/dataverse-uploader@v1.2
72+
with:
73+
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
74+
DATAVERSE_SERVER: https://demo.dataverse.org
75+
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
76+
GITHUB_DIR: data
77+
DELETE: False
7478
```
7579

76-
Upon upload, the action will automatically publish a new version of the Dataverse dataset by default. If you'd like to create a new version manually, set the `PUBLISH` argument to `False`.
80+
The action automatically uploads new content to a Dataverse dataset, but it will not publish it as a
81+
new version by default. If you'd like the action to publish a new dataset version in Dataverse,
82+
set the `PUBLISH` argument to `True`.
7783

7884
```
79-
jobs:
80-
build:
81-
runs-on: ubuntu-latest
82-
steps:
83-
- name: Send repo to Dataverse
84-
uses: IQSS/dataverse-uploader@v1.1
85-
with:
86-
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
87-
DATAVERSE_SERVER: https://demo.dataverse.org
88-
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
89-
GITHUB_DIR: data
90-
DELETE: False
91-
PUBLISH: False
85+
steps:
86+
- name: Send repo to Dataverse
87+
uses: IQSS/dataverse-uploader@v1.2
88+
with:
89+
DATAVERSE_TOKEN: ${{secrets.DATAVERSE_TOKEN}}
90+
DATAVERSE_SERVER: https://demo.dataverse.org
91+
DATAVERSE_DATASET_DOI: doi:10.70122/FK2/LVUA
92+
GITHUB_DIR: data
93+
DELETE: False
94+
PUBLISH: True
9295
```
9396

97+
## Q&A
98+
99+
> If you change the content of your GitHub repository, are the changes synchronized in Dataverse?
100+
> Otherwise, is it possible to synchronize them automatically?
101+
102+
Yes, the action is able to automatically update the Dataverse dataset. In other words, if the action
103+
is triggered with every `push` to the GitHub repository, it will automatically upload its content to
104+
Dataverse. You specify the action triggers in the workflow (`.yml`) file, and in this case, it would
105+
contain `on: push` line to execute the action on every push to the repository.
106+
94107
## Related projects
95108

96109
Check out the following related projects:
@@ -105,6 +118,10 @@ Visit [this page](https://atrisovic.github.io/dataverse-badge/) to create a Data
105118

106119
Looking for a stand-alone Dataverse uploader that will work from the command line? Check out [DVUploader](https://github.com/GlobalDataverseCommunityConsortium/dataverse-uploader).
107120

121+
## References
122+
123+
See the official Dataverse documentation [here](https://guides.dataverse.org/en/latest/admin/integrations.html#id10).
124+
108125
## Contact
109126

110127
Don't hesitate to create an issue, a pull request, or contact us if you notice any problems with the action.

‎dataverse.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ def parse_arguments():
2525
parser.add_argument(
2626
"-p", "--publish", help="Publish a new dataset version after upload.", \
2727
choices=('True', 'TRUE', 'true', 'False', 'FALSE', 'false'), \
28-
default='true')
28+
default='false')
2929

3030
args_ = parser.parse_args()
3131
return args_

0 commit comments

Comments
 (0)