| Name | gitbugactions JSON |
| Version |
3.1.0
JSON |
| download |
| home_page | None |
| Summary | A tool that builds bug-fix benchmarks by leveraging GitHub Actions. |
| upload_time | 2024-12-28 12:25:04 |
| maintainer | None |
| docs_url | None |
| author | Nuno Saavedra |
| requires_python | <4.0,>=3.12 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# GitBug-Actions
GitBug-Actions is a tool that builds bug-fix benchmarks by leveraging GitHub Actions.
The tool mines GitHub repositories and navigates through their commits, locally executing GitHub Actions using [act](https://github.com/gitbugactions/act) in each commit considered.
Finally, the tool checks if a bug-fix pattern was found by looking at the test results parsed from the GitHub Actions runs.
If a bug-fix is found, GitBug-Actions is able to export a Docker image with the reproducible environment for the bug-fix.
The reproducible environment will preserve all the dependencies required to run the tests for the bug-fix, avoiding the degradation of the benchmark due to dependencies that become unavailable.
If you use GitBug-Actions, please cite:
[GitBug-Actions: Building Reproducible Bug-Fix Benchmarks with GitHub Actions](http://arxiv.org/pdf/2310.15642) ([doi:10.1145/3639478.3640023](https://doi.org/10.1145/3639478.3640023))
```
@inproceedings{gitbugactions,
title = {GitBug-Actions: Building Reproducible Bug-Fix Benchmarks with GitHub Actions},
year = {2024},
doi = {10.1145/3639478.3640023},
author = {Saavedra, Nuno and Silva, Andr{\'e} and Monperrus, Martin},
booktitle = {Proceedings of the ACM/IEEE 46th International Conference on Software Engineering: Companion Proceedings},
}
```
## Requirements
### Act
It is required to have [act](https://github.com/gitbugactions/act) installed and functional.
At the moment, GitBug-Actions only works correctly with the modified version of `act` available [here](https://github.com/gitbugactions/act).
Other versions will work but some issues may arise.
To install this version:
```
git clone https://github.com/gitbugactions/act
cd act
make build
```
A binary file `dist/local/act` will be created. This binary file should be made available in the `$PATH` of the system:
```
export PATH="<REPLACE_WITH_PATH_TO_ACT>:$PATH"
```
### Python dependencies
GitBug-Actions runs on Python3.12 and above.
Ensure Poetry is [installed](https://python-poetry.org/docs/#installation).
Then, to install the Python dependencies run:
```
poetry shell
poetry install
```
## How to run
Ensure the commands are executed inside the Poetry shell:
```
poetry shell
```
Set the environment variable `GITHUB_ACCESS_TOKEN` with your [GitHub access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). The token is used to perform calls to GitHub's API.
```
export GITHUB_ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
```
Use the `--help` command to obtain the list of options required to run each script.
```
python collect_repos.py --help
python collect_bugs.py --help
python export_bugs.py --help
python filter_bugs.py --help
```
The figure above provides an overview of the pipeline of GitBug-Actions.
The scripts above should be executed in the same order shown on the figure.
`collect_bugs` will use the repositories found by `collect_repos` as input.
`export_bugs` uses the bug-fixes found by `collect_bugs` as input.
Finally, `filter_bugs` uses the bug-fixes found by `collect_bugs` and the containers exported by `export_bugs` as input.
The output of `filter_bugs` is a file with a list of non-flaky bug-fixes able to be reproduced in the exported containers.
## Tests
To run the tests:
```
pytest test -s
```
## Practical Challenges
While developing GitBug-Actions, we found some challenges of running CI builds at a large scale.
Here we enumerate these challenges and explain how we mitigate them and, in cases that was not possible, **how the user should handle them**.
### Handling Commits without GitHub Actions
One challenge in collecting bug-fix commit pairs by reproducing GitHub Actions is that GitHub Actions were only released in late 2019.
Moreover, albeit being the most popular as of 2023, its adoption was not immediate.
As a result the majority of commits found on GitHub do not have any associated workflows.
To increase the number of supported commits by GitBug-Actions, it identifies the oldest locally reproducible GitHub Action for each project.
Then, for commits not associated with GitHub Actions, GitBug-Actions uses these as an approximation of the intended configuration.
### Disk Space Management
Build execution has the potential to exhaust available disk space.
To mitigate this, we restrict each build's allocation to a maximum of 3GiB. This restriction is handled by our version of [act](https://github.com/gitbugactions/act).
However, users are advised to check disk usage frequently and remove dangling docker containers/images in case they occur. Additionally, users should take special attention to docker volumes which are not automatically removed by act, and can accumulate over time.
Example of how to remove dangling containers and volumes created by act:
```bash
# Remove containers
docker rm $(docker stop $(docker ps -a -q --filter ancestor=gitbugactions:latest --format="{{.ID}}"))
# Remove volumes
docker volume ls -q | grep '^act-' | xargs docker rm
```
### Concurrent File Access
CI builds may initiate concurrent file access operations, a situation that can escalate to the point of surpassing the user-level open-file limit set by Linux.
This is exarcebated when running multiple builds in parallel.
To overcome this, we recommend setting the open-file limit for your user profile to a higher threshold than the default.
To check the current limit for your user run `ulimit -Sn`.
## Contributing
Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.
Please make sure to update tests as appropriate.
## License
[MIT](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "gitbugactions",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Nuno Saavedra",
"author_email": "nuno.saavedra@tecnico.ulisboa.pt",
"download_url": "https://files.pythonhosted.org/packages/e4/5e/2c6e106d037d1111bfa2558d50603d4733a2cb7e01d7394078ec3f12fe2a/gitbugactions-3.1.0.tar.gz",
"platform": null,
"description": "# GitBug-Actions\n\nGitBug-Actions is a tool that builds bug-fix benchmarks by leveraging GitHub Actions.\nThe tool mines GitHub repositories and navigates through their commits, locally executing GitHub Actions using [act](https://github.com/gitbugactions/act) in each commit considered.\nFinally, the tool checks if a bug-fix pattern was found by looking at the test results parsed from the GitHub Actions runs. \nIf a bug-fix is found, GitBug-Actions is able to export a Docker image with the reproducible environment for the bug-fix.\nThe reproducible environment will preserve all the dependencies required to run the tests for the bug-fix, avoiding the degradation of the benchmark due to dependencies that become unavailable.\n\nIf you use GitBug-Actions, please cite:\n\n[GitBug-Actions: Building Reproducible Bug-Fix Benchmarks with GitHub Actions](http://arxiv.org/pdf/2310.15642) ([doi:10.1145/3639478.3640023](https://doi.org/10.1145/3639478.3640023))\n\n```\n@inproceedings{gitbugactions,\n title = {GitBug-Actions: Building Reproducible Bug-Fix Benchmarks with GitHub Actions},\n year = {2024},\n doi = {10.1145/3639478.3640023},\n author = {Saavedra, Nuno and Silva, Andr{\\'e} and Monperrus, Martin},\n booktitle = {Proceedings of the ACM/IEEE 46th International Conference on Software Engineering: Companion Proceedings},\n}\n```\n\n## Requirements\n\n### Act\n\nIt is required to have [act](https://github.com/gitbugactions/act) installed and functional.\nAt the moment, GitBug-Actions only works correctly with the modified version of `act` available [here](https://github.com/gitbugactions/act).\nOther versions will work but some issues may arise.\n\nTo install this version:\n```\ngit clone https://github.com/gitbugactions/act\ncd act\nmake build\n```\n\nA binary file `dist/local/act` will be created. This binary file should be made available in the `$PATH` of the system:\n```\nexport PATH=\"<REPLACE_WITH_PATH_TO_ACT>:$PATH\"\n```\n\n### Python dependencies\n\nGitBug-Actions runs on Python3.12 and above.\n\nEnsure Poetry is [installed](https://python-poetry.org/docs/#installation).\n\nThen, to install the Python dependencies run:\n```\npoetry shell\npoetry install\n```\n\n## How to run\n\nEnsure the commands are executed inside the Poetry shell:\n\n```\npoetry shell\n```\n\nSet the environment variable `GITHUB_ACCESS_TOKEN` with your [GitHub access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). The token is used to perform calls to GitHub's API.\n```\nexport GITHUB_ACCESS_TOKEN=\"<YOUR_ACCESS_TOKEN>\"\n```\n\nUse the `--help` command to obtain the list of options required to run each script.\n\n```\npython collect_repos.py --help\npython collect_bugs.py --help\npython export_bugs.py --help\npython filter_bugs.py --help\n```\n\n\n\nThe figure above provides an overview of the pipeline of GitBug-Actions.\n\nThe scripts above should be executed in the same order shown on the figure. \n`collect_bugs` will use the repositories found by `collect_repos` as input.\n`export_bugs` uses the bug-fixes found by `collect_bugs` as input.\nFinally, `filter_bugs` uses the bug-fixes found by `collect_bugs` and the containers exported by `export_bugs` as input.\nThe output of `filter_bugs` is a file with a list of non-flaky bug-fixes able to be reproduced in the exported containers.\n\n## Tests\n\nTo run the tests:\n\n```\npytest test -s\n```\n\n## Practical Challenges\n\nWhile developing GitBug-Actions, we found some challenges of running CI builds at a large scale. \nHere we enumerate these challenges and explain how we mitigate them and, in cases that was not possible, **how the user should handle them**.\n\n### Handling Commits without GitHub Actions\n\nOne challenge in collecting bug-fix commit pairs by reproducing GitHub Actions is that GitHub Actions were only released in late 2019.\nMoreover, albeit being the most popular as of 2023, its adoption was not immediate.\nAs a result the majority of commits found on GitHub do not have any associated workflows.\n\nTo increase the number of supported commits by GitBug-Actions, it identifies the oldest locally reproducible GitHub Action for each project.\nThen, for commits not associated with GitHub Actions, GitBug-Actions uses these as an approximation of the intended configuration.\n\n### Disk Space Management\n\nBuild execution has the potential to exhaust available disk space.\nTo mitigate this, we restrict each build's allocation to a maximum of 3GiB. This restriction is handled by our version of [act](https://github.com/gitbugactions/act).\n\nHowever, users are advised to check disk usage frequently and remove dangling docker containers/images in case they occur. Additionally, users should take special attention to docker volumes which are not automatically removed by act, and can accumulate over time.\n\nExample of how to remove dangling containers and volumes created by act:\n```bash\n# Remove containers\ndocker rm $(docker stop $(docker ps -a -q --filter ancestor=gitbugactions:latest --format=\"{{.ID}}\"))\n# Remove volumes\ndocker volume ls -q | grep '^act-' | xargs docker rm\n```\n\n### Concurrent File Access\n\nCI builds may initiate concurrent file access operations, a situation that can escalate to the point of surpassing the user-level open-file limit set by Linux.\nThis is exarcebated when running multiple builds in parallel.\nTo overcome this, we recommend setting the open-file limit for your user profile to a higher threshold than the default.\n\nTo check the current limit for your user run `ulimit -Sn`.\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first\nto discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License\n\n[MIT](LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool that builds bug-fix benchmarks by leveraging GitHub Actions.",
"version": "3.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a42f0593c186081d86d378e636381730fdb961617154ebe38e16966f258d36d7",
"md5": "bd0b36e75f9093bc92c5cce33ffd23b6",
"sha256": "e58ac50aadacb22631aaae24ec9990cf9e3e129037d20932d73e13335760d796"
},
"downloads": -1,
"filename": "gitbugactions-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd0b36e75f9093bc92c5cce33ffd23b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 61082,
"upload_time": "2024-12-28T12:25:02",
"upload_time_iso_8601": "2024-12-28T12:25:02.260951Z",
"url": "https://files.pythonhosted.org/packages/a4/2f/0593c186081d86d378e636381730fdb961617154ebe38e16966f258d36d7/gitbugactions-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e45e2c6e106d037d1111bfa2558d50603d4733a2cb7e01d7394078ec3f12fe2a",
"md5": "eb95e7af1de55ec50852936965baa0b4",
"sha256": "bb83ee2282a51064ccac2c8f6c575fafac9199fdbe67ef1aacd99192451a1673"
},
"downloads": -1,
"filename": "gitbugactions-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "eb95e7af1de55ec50852936965baa0b4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 50332,
"upload_time": "2024-12-28T12:25:04",
"upload_time_iso_8601": "2024-12-28T12:25:04.037255Z",
"url": "https://files.pythonhosted.org/packages/e4/5e/2c6e106d037d1111bfa2558d50603d4733a2cb7e01d7394078ec3f12fe2a/gitbugactions-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-28 12:25:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gitbugactions"
}
