{"id":25631235,"url":"https://github.com/boompig/secret-santa","last_synced_at":"2026-06-17T18:04:39.001Z","repository":{"id":47754615,"uuid":"114801327","full_name":"boompig/secret-santa","owner":"boompig","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-02T01:40:07.000Z","size":176,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-07T16:23:41.430Z","etag":null,"topics":["cryptography","gmail-api","python3","tox"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boompig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-12-19T19:05:24.000Z","updated_at":"2026-01-02T01:40:11.000Z","dependencies_parsed_at":"2023-01-24T21:45:34.940Z","dependency_job_id":null,"html_url":"https://github.com/boompig/secret-santa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/boompig/secret-santa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boompig%2Fsecret-santa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boompig%2Fsecret-santa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boompig%2Fsecret-santa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boompig%2Fsecret-santa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boompig","download_url":"https://codeload.github.com/boompig/secret-santa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boompig%2Fsecret-santa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34459640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["cryptography","gmail-api","python3","tox"],"created_at":"2025-02-22T20:19:32.680Z","updated_at":"2026-06-17T18:04:38.996Z","avatar_url":"https://github.com/boompig.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\nRun this script to create secret Santa pairings and distribute them.\n\n## What Does It Do?\n\n1. Create Secret Santa pairings from a pre-defined group of people (participants), with support for direction pairing exclusions and locked-in \"always\" pairings.\n2. Distribute the pairings to the participants either via SMS or via email. Supports custom messages that can be formatted with some variables.\n    * Can encrypt/obfuscate the pairings behind a link such that the email inbox of the person sending the pairings will not leak the pairings by accident.\n3. Save pairings such that they can be resent if needed, or for later analysis or sanity checking.\n\nSupports running multiple \"campaigns\" at once that can contain the same or different group of participants.\n\n## Setup (Installation)\n\nThis project uses the `uv` package manager. Run `uv sync` to install deps.\n\n## How to Run\n\nBroadly speaking, you will need to only change a few files in the `config` directory.\nI recommend creating a single data directory for a specific campaign (e.g. `config/disco_2025`).\n\n1. create file `config/credentials.json` which contains `email` and `application_specific_password` fields for Gmail.\n2. create file `config/{campaign_name}/names.json` whose contents should two keys:\n    - `names`: map from names to object with key `email` (mapping to email) or `text` (mapping to number to use for SMS)\n    - `constraints` (optional): has keys `always` and `never`. Each is a list, where each item is a list of two names. First name is giver and second name is receiver.\n3. create file `config/{campaign_name}/instructions_email.md` whose contents are the text of the email. Use python-format style formatting for string substitutions. Available variables are `giver_name` and `link`.\n4. create file `config/{campaign_name}/config.json` which has these keys:\n    - `email_subject` - the email subject\n    - `year` - current year\n\n```bash\nuv run -m secret_santa --encrypt --live\n```\n\nThe `--help` switch is also available and gives additional options. A directory called `data` will be created with files for debugging.\n\n## Development\n\n`uv` to install deps, point your IDE at the `.venv` folder created by `uv`.\n\n## Testing\n\nThis project previously used `tox` but now uses `task`. See `Taskfile.yml`.\n\n## Debugging\n\nEmails are saved to `data/emails/\u003cgiver_name\u003e.html` before they are sent.\nMarkdown files for emails are also created before being converted into HTML and are saved in `data/markdown`.\nThe `data/html` directory contains identical data to `data/emails` unless something has gone very wrong.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboompig%2Fsecret-santa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboompig%2Fsecret-santa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboompig%2Fsecret-santa/lists"}