{"id":19184626,"url":"https://github.com/gatoreducator/sheetshuttle","last_synced_at":"2025-07-23T03:05:59.688Z","repository":{"id":38006795,"uuid":"402781399","full_name":"GatorEducator/SheetShuttle","owner":"GatorEducator","description":":truck: A plugin friendly tool to connect Google Sheets and GitHub","archived":false,"fork":false,"pushed_at":"2022-12-12T22:23:31.000Z","size":4917,"stargazers_count":3,"open_issues_count":8,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-23T02:40:39.149Z","etag":null,"topics":["github","google-sheets-api","pluginbase","pygithub","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GatorEducator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-03T13:34:45.000Z","updated_at":"2023-02-06T15:55:52.000Z","dependencies_parsed_at":"2023-01-28T02:15:23.823Z","dependency_job_id":null,"html_url":"https://github.com/GatorEducator/SheetShuttle","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GatorEducator/SheetShuttle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GatorEducator%2FSheetShuttle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GatorEducator%2FSheetShuttle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GatorEducator%2FSheetShuttle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GatorEducator%2FSheetShuttle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GatorEducator","download_url":"https://codeload.github.com/GatorEducator/SheetShuttle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GatorEducator%2FSheetShuttle/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266609073,"owners_count":23955569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","google-sheets-api","pluginbase","pygithub","python"],"created_at":"2024-11-09T11:07:42.009Z","updated_at":"2025-07-23T03:05:59.658Z","avatar_url":"https://github.com/GatorEducator.png","language":"Python","readme":"# SheetShuttle\n\n![License](https://img.shields.io/badge/license-MIT-blue?style=flat)\n![BuiltWith](https://img.shields.io/badge/Built%20With-Python-blue?style=flat\u0026logo=python\u0026logoColor=yellow)\n![Actions Status](https://github.com/noorbuchi/SheetShuttle/workflows/Lint%20and%20Test/badge.svg)\n[![codecov](https://codecov.io/gh/noorbuchi/SheetShuttle/branch/main/graph/badge.svg?token=02353FAN4W)](https://codecov.io/gh/noorbuchi/SheetShuttle)\n![stars](https://img.shields.io/github/stars/noorbuchi/SheetShuttle.svg)\n\n![SheetShuttleLogo](images/Logo.png)\n\nSheetShuttle is a plugin friendly tool that connects Google Sheets\nand GitHub by allowing the user to post collected data to issue trackers, pull\nrequests, and files. The tool\nprovides and object oriented API and encourages users to utilize it in their\napplications.\n\n- [SheetShuttle](#sheetshuttle)\n  - [Set Up and Installation](#set-up-and-installation)\n    - [Recommended Installation Using `pip`](#recommended-installation-using-pip)\n    - [Manually Building SheetShuttle](#manually-building-sheetshuttle)\n  - [Running SheetShuttle](#running-sheetshuttle)\n    - [API Setup](#api-setup)\n      - [Google Sheets Service Account](#google-sheets-service-account)\n      - [Github Access Token](#github-access-token)\n    - [Writing Config](#writing-config)\n      - [Sheets Collector](#sheets-collector)\n      - [Github Interactions](#github-interactions)\n    - [Using Command Line Interface](#using-command-line-interface)\n      - [Initialize a New Plugin](#initialize-a-new-plugin)\n      - [Running an Existing Plugin](#running-an-existing-plugin)\n    - [Plugin System](#plugin-system)\n  - [Contributors ✨](#contributors-)\n\n## Set Up and Installation\n\n### Recommended Installation Using `pip`\n\nSheetShuttle can be installed using Python's package manager `pip`. By running\nthe following command, SheetShuttle and all its dependencies are installed.\n\n```shell\npip install sheetshuttle\n```\n\nUsing this command to install SheetShuttle will ensure that you have the latest\nmost stable version of the tool. Additionally, you will be able to run the tool\nanywhere on your system using the `sheetshuttle` command.\n\n### Manually Building SheetShuttle\n\nTo get the latest changes from `main` or other development branches, make sure\nto clone the project's repository and follow these steps to create Python\nvirtual environment, install dependencies, and build the tool.\n\nSheetShuttle uses Poetry to create a Python virtual environment and manage\ndependencies. For more information about Poetry, check out [the\ndocumentation](https://python-poetry.org/). To set up the tool for use, please\nfollow the steps outlined below:\n\n**1- Install Poetry:**\n\nInstall Poetry using the steps outlined\n[here](https://python-poetry.org/docs/#installation). To verify that Poetry was\ninstalled successfully run the following:\n\n```shell\npoetry -V\n```\n\nThe expected output is the version of Poetry installed.\n\n**2- Install Python Dependencies:**\n\nOnce Poetry has been installed successfully, clone or download the repository\nand navigate to the root of the repository. Use the following command to install\nall the dependencies used by SheetShuttle:\n\n```shell\npoetry install\n```\n\nThis command might take some time to finish running. Once it is completed,\nSheetShuttle is ready for use!\n\n**3- Build SheetShuttle or Run Using Poetry:**\n\nAfter the development environment is ready, you can build an installable `.whl`\nfile using `poetry build` command, or continue to use the tool by running\n`poetry run sheetshuttle` from the project directory and passing any additional\nCLI arguments.\n\n## Running SheetShuttle\n\nFor a thorough steps refer to this [tutorial](docs/tutorial.md)\n\n### API Setup\n\nSheetShuttle requires authentication tokens for a Google Sheets API service\naccount. A GitHub access token is also needed if some features are used. To set\nup a service account and get the tokens, please follow the steps below:\n\n#### Google Sheets Service Account\n\n[This tutorial](https://youtu.be/4ssigWmExak?t=215)\nfrom `3:35` until `8:20` gives clear and\ndetailed steps on how to create a service account and create an authentication\nkey. However, it includes extra steps that not everyone will need to follow. You\ncan follow the video if preferred or the [Sheets API\nGuide](docs/Google_API_Setup.md).\n\nOnce API credentials have been downloaded, there are 2 ways to allow SheetShuttle\nto use them.\n\n1. Place the downloaded JSON file in the root of the project repository\n1. OR create a new `.env` file and transfer the information from the `.json`\n   file to the environment file in the following format.\n\n**Important Note:** Values in the `.env` file must be surrounded\nby double quotation marks `\"` otherwise, newline character `\\n`\nwill cause issues.\n\nNote that variable names must be in upper case.\n\n```.evn\nTYPE=\"value\"\nPROJECT_ID=\"value\"\nPRIVATE_KEY_ID=\"value\"\nPRIVATE_KEY=\"value\"\nCLIENT_EMAIL=\"value\"\nCLIENT_ID=\"value\"\nAUTH_URI=\"value\"\nTOKEN_URI=\"value\"\nAUTH_PROVIDER_X509_CERT_URL=\"value\"\nCLIENT_X509_CERT_URL=\"value\"\n```\n\n#### Github Access Token\n\nIf you intend to use SheetShuttle's GitHub interactions features, it is\nrequired to create a GitHub access token and place it correctly in\nthe project repository. To create a token, please use the official\nguide found\n[here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).\nThe created token should be granted `repo` access.\n\nOnce a token has been created, there are two ways to allow SheetShuttle\nto use it:\n\n1. Create a json file in the repository root with the following format (note\n   that the `gh_access_token` key is required):\n\n   ```json\n   {\n     \"gh_access_token\": \"paste your token here\"\n   }\n   ```\n\n1. OR add a variable to the `.env` file in the following format\n\n     ```.env\n     GH_ACCESS_TOKEN=\"paste your token here\"\n     ```\n\n### Writing Config\n\nSheetShuttle relies on user written YAML configuration to\ncollect data from Google Sheets and organize it in regions.\nGitHub interactions are also managed by\nYAML configuration. To read more about the structure of SheetShuttle\nconfiguration, please refer to our [schema documentation](docs/schemas.md).\n\n#### Sheets Collector\n\nSheets Collector is the component of SheetShuttle that is responsible\nfor making Google Sheets API calls and retrieving data from user\nspecified files and sheets. Additionally, it creates an object\noriented structure for regions and sheets of data.\nIn order to use this component, configuration YAML files are needed\nin the `config/sheet_sources` directory. Multiple files can be used if multiple\nsheets are being read at the same time.\n\n#### Github Interactions\n\nAnother component of SheetShuttle is the GitHub Interaction interface. It is\nresponsible for making API requests to GitHub and posting user specified\ninformation to GitHub in the form of issue trackers, ull requests, and files.\nThe user has complete control of this component's behavior through YAML\nconfiguration files found in `config/github_interactions` directory. Multiple\nfiles can be used if preferred.\n\n### Using Command Line Interface\n\nAfter installing SheetShuttle using `pip`, the command `sheetshuttle` becomes\navailable to run the tool from any location on your system. To get help on the\nCLI commands for SheetShuttle, you can always run `sheetshuttle --help` to get\nthe available options. This section gives additional details on the available\nsubcommands for the tool.\n\n#### Initialize a New Plugin\n\nTo make the process of creating a new plugin more convenient and less error\nprone, the `init` command will create a plugin template that\nfulfils the structural requirement.\n\n```shell\nsheetshuttle init my_plugin_name\n```\n\nThis command creates a Python file named `my_plugin_name.py` in the same\ndirectory the command was ran in. This file can then be edited and used as the\nplugin for SheetShuttle.\n\n#### Running an Existing Plugin\n\nThe `run` command is responsible for executing a user defined plugin. It\nsupports a help message that displays all the available arguments and their\ndescription. Some of these arguments are required while others are optional.\nAdditionally, most of them already hold a default value that gets used when no\nvalue is passed through the command.\n\n```shell\n$ sheetshuttle run --help\n\nUsage: sheetshuttle run [OPTIONS]\n\n  Run sheetshuttle using your custom plugin.\n\nOptions:\n  -kf, --sheets-keys-file TEXT    Path to the Sheets api keys, either .json or\n                                  .env file  [default: .env]\n\n  -sd, --sheets-config-directory TEXT\n                                  Directory to get the sheets configuration\n                                  .yaml files from  [default:\n                                  config/sheet_sources/]\n\n  -gd, --gh-config-directory TEXT\n                                  Directory to get the Github configuration\n                                  .yaml files from  [default:\n                                  config/gh_sources/]\n\n  -pd, --plugins-directory TEXT   Directory to get plugins from  [default:\n                                  plugins/]\n\n  -pn, --plugin-name TEXT         Name of plugin to use for processing\n                                  [default: default]\n\n  -ja, --json-args TEXT           Path to the JSON file with additional\n                                  arguments. [Optional]\n\n  --help                          Show this message and exit.\n\n```\n\n### Plugin System\n\nSheetShuttle supports user defined plugins that use the API provided by the\ntool. These plugins typically follow a specific format where they must contain a\n`run` function. When the directory and name of the plugin are provided in the\n`sheetshuttle run` command, the plugin is validated and then immediately ran.\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/noorbuchi\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/55197145?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNoor Buchi\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/GatorEducator/SheetShuttle/commits?author=noorbuchi\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/GatorEducator/SheetShuttle/commits?author=noorbuchi\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#plugin-noorbuchi\" title=\"Plugin/utility libraries\"\u003e🔌\u003c/a\u003e \u003ca href=\"https://github.com/GatorEducator/SheetShuttle/pulls?q=is%3Apr+reviewed-by%3Anoorbuchi\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"https://github.com/GatorEducator/SheetShuttle/commits?author=noorbuchi\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#projectManagement-noorbuchi\" title=\"Project Management\"\u003e📆\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://tommyantle.netlify.app/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/55158626?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eTommy Antle\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/GatorEducator/SheetShuttle/commits?author=antlet\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/GatorEducator/SheetShuttle/pulls?q=is%3Apr+reviewed-by%3Aantlet\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/tuduun\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/62280291?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003etuduun\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/GatorEducator/SheetShuttle/commits?author=tuduun\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/GatorEducator/SheetShuttle/pulls?q=is%3Apr+reviewed-by%3Atuduun\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Yanqiao4396\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/79415648?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eYanqiao4396\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/GatorEducator/SheetShuttle/commits?author=Yanqiao4396\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/GatorEducator/SheetShuttle/pulls?q=is%3Apr+reviewed-by%3AYanqiao4396\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://www.gregorykapfhammer.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/926029?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGregory M. Kapfhammer\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#mentoring-gkapfham\" title=\"Mentoring\"\u003e🧑‍🏫\u003c/a\u003e \u003ca href=\"#projectManagement-gkapfham\" title=\"Project Management\"\u003e📆\u003c/a\u003e \u003ca href=\"#ideas-gkapfham\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://www.douglasjluman.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1552764?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDouglas Luman\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-dluman\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#design-dluman\" title=\"Design\"\u003e🎨\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgatoreducator%2Fsheetshuttle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgatoreducator%2Fsheetshuttle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgatoreducator%2Fsheetshuttle/lists"}