{"id":18793074,"url":"https://github.com/dsacms/iv-cbv-payroll","last_synced_at":"2025-04-13T14:31:52.261Z","repository":{"id":242610184,"uuid":"790448083","full_name":"DSACMS/iv-cbv-payroll","owner":"DSACMS","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-06T20:25:25.000Z","size":20993,"stargazers_count":2,"open_issues_count":7,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-06T21:29:02.446Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DSACMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS.md","security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-22T22:34:18.000Z","updated_at":"2024-11-06T20:20:49.000Z","dependencies_parsed_at":"2024-06-10T18:31:09.332Z","dependency_job_id":"1b1803ae-b13b-4dd7-878f-716268564bec","html_url":"https://github.com/DSACMS/iv-cbv-payroll","commit_stats":null,"previous_names":["dsacms/iv-cbv-payroll"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-cbv-payroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-cbv-payroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-cbv-payroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-cbv-payroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DSACMS","download_url":"https://codeload.github.com/DSACMS/iv-cbv-payroll/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223590250,"owners_count":17170102,"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","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":[],"created_at":"2024-11-07T21:23:26.472Z","updated_at":"2025-04-13T14:31:52.255Z","avatar_url":"https://github.com/DSACMS.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Income Verification: Consent-Based Verification (Payroll)\n========================\n\n# About the Project\n\nConsent-Based Verification (CBV) is a prototype that allows benefit applicants to verify their income directly using payroll providers. It is currently being piloted for testing and validation purposes.\n\n# Development and Software Delivery Lifecycle\n\nIf you're new to Rails, see the [Getting Started with Rails](https://guides.rubyonrails.org/getting_started.html)\nguide for an introduction to the framework.\n\n## Setup\n\nMost developers on the team code using macOS, so we recommend that platform if possible. Some of these steps may not apply to other platforms.\n\n1. Install Xcode Command Line Tools: ```xcode-select --install```\n1. Install homebrew dependencies: `brew bundle`\n   * rbenv\n   * nodenv\n   * [redis]()\n   * [jq](https://stedolan.github.io/jq/)\n   * [PostgreSQL](https://www.postgresql.org/)\n   * [Dockerize](https://github.com/jwilder/dockerize)\n   * [ADR Tools](https://github.com/npryce/adr-tools)\n   * [Graphviz](https://voormedia.github.io/rails-erd/install.html): brew install graphviz\n   * [Chromedriver](https://sites.google.com/chromium.org/driver/)\n     * Chromedriver must be allowed to run. You can either do that by:\n       * The command line: `xattr -d com.apple.quarantine $(which chromedriver)` (this is the only option if you are on Big Sur)\n       * Manually: clicking \"allow\" when you run the integration tests for the first time and a dialogue opens up\n   * [Ngrok](https://ngrok.com/downloads): brew install ngrok/ngrok/ngrok\n     * Sign up for an account: https://dashboard.ngrok.com/signup\n     * run `ngrok config add-authtoken {token goes here}`\n   * [pre-commit](https://pre-commit.com/)\n     * This configures your local git to run linters locally during a git commit. See [#coding-style-and-linters](#coding-style-and-linters) for a summary of which ones we use.\n     * Run `pre-commit install` to opt-into running these linters. (They will run during CI regardless.)\n1. Set up rbenv and nodenv:\n   * `echo 'if which nodenv \u003e/dev/null 2\u003e/dev/null; then eval \"$(nodenv init -)\"; fi' \u003e\u003e ~/.zshrc`\n   * `echo 'if which rbenv \u003e/dev/null 2\u003e/dev/null; then eval \"$(rbenv init -)\"; fi' \u003e\u003e ~/.zshrc`\n   * Close \u0026 re-open your terminal\n\n**The following commands must be run in the app directory**\n1. Install Ruby: `rbenv install`\n1. Install NodeJS `nodenv install`\n1. Install Ruby dependencies: `bundle install`\n   * If you get an error from debase, run this command: ```gem install debase -v0.2.5.beta2 -- --with-cflags=\"-Wno-incompatible-function-pointer-types\"```\n   * Also we should probably fix this (TODO)\n1. Install JS dependencies\n   * `nodenv rehash`\n   * `npm install`\n1. Start postgres \u0026 redis:\n   * `brew services start postgresql@12`\n   * `brew services start redis`\n1. Get development credentials from 1Password: search for \"CBV .env.local secrets\" and copy its \".env.local\" section into a file called that in the app directory.\n1. Create database: `bin/rails db:create`\n1. Run migrations: `bin/rails db:migrate`\n1. Run the development server: `bin/dev`\n1. Visit the site: http://localhost:3000\n\n## Local Development\n\nEnvironment variables can be set in development using the [dotenv](https://github.com/bkeepers/dotenv) gem.\n\nAny changes to variables in `.env` that should not be checked into git should be set in `.env.local`.\n\nFor a list of **which environment variables can be modified for local development**, see the comments in `.env.local`.\n\nIf you wish to override a config globally for the `test` Rails environment you can set it in `.env.test.local`.\nHowever, any config that should be set on other machines should either go into `.env` or be explicitly set as part\nof the test.\n\nTo run locally, use `bin/dev`\n\nTo run database migrations on the test environment that is used by rpec tests, run `RAILS_ENV=test bin/rails db:schema:load`\n\n## Branching model\nWhen beginning work on a feature, create a new branch based off of `main` and make the commits for that feature there.\n\nWe intend to use short-lived branches so as to minimize the cost of integrating each feature into the main branch.\n\n## Story Acceptance\n\nWe strive for all features to be acceptance tested prior to merge. The process is outline in the [Github PR Template](/.github/pull_request_template.md).\n\n# Security\n\n## Authentication\n\nTBD\n\n## Inline `\u003cscript\u003e` and `\u003cstyle\u003e` security\n\nThe system's Content-Security-Policy header prevents `\u003cscript\u003e` and `\u003cstyle\u003e` tags from working without further\nconfiguration. Use `\u003c%= javascript_tag nonce: true %\u003e` for inline javascript.\n\n# Internationalization\n\n## Managing locale files\n\nWe use the gem `i18n-tasks` to manage locale files. Here are a few common tasks:\n\nAdd missing keys across locales:\n```\n$ i18n-tasks missing # shows missing keys\n$ i18n-tasks add-missing # adds missing keys across locale files\n```\n\nKey sorting:\n```\n$ i18n-tasks normalize\n```\n\nRemoving unused keys:\n```\n$ i18n-tasks unused # shows unused keys\n$ i18n-tasks remove-unused # removes unused keys across locale files\n```\n\nFor more information on usage and helpful rake tasks to manage locale files, see [the documentation](https://github.com/glebm/i18n-tasks#usage).\n\n## \"Client Agency-specific\" translations\n\nThe CBV pilot project is architected to be multi-tenant across jurisdictions we\nare actively piloting with. Each jurisdiction's agency is configured as a\n\"client agency\" in app/config/client-agency-config.yml and has a short \"id\", e.g. \"nyc\", \"ma\",\nand \"sandbox\".\n\nWe often need to adjust copy specific to each client agency. The preferred way to do it\nis by using the `client_agency_translation` helper, which wraps Rails's `t` view helper\nand looks for the current client agency's \"id\" as a sub-key of the given prefix.\n\nUsage:\n\n```erb\n\u003c%= client_agency_translation(\".learn_more_html\") %\u003e\n```\n\nAnd the corresponding locale file:\n\n\n```yaml\nlearn_more_html:\n  nyc: Learn more about \u003cstrong\u003eNYC Human Resources Administration\u003c/strong\u003e\n  ma: Learn more about \u003cstrong\u003eMassachusetts Department of Transitional Assistance\u003c/strong\u003e\n  sandbox: Learn more about \u003cstrong\u003eCBV Test Agency\u003c/strong\u003e\n  default: Learn more about \u003cstrong\u003eDefault Agency\u003c/strong\u003e\n```\n\nSimilar to Rails's `t` helper, the string will be marked HTML-safe if its key\nprefix ends with `_html`.\n\n## Importing Translations\n\nWe have a custom rake task and translation service for importing translations from CSV files to YAML format. This allows for easy management and updating of locale files.\n\nThe service handles nested keys and maintains the hierarchical structure of the YAML file by merging the new locale entries with the existing ones.\n\n\n### How the Translation Service Works\n\n1. The service reads the specified CSV file from the `tmp` directory.\n2. It processes each row, skipping empty rows or those marked as not needing translation.\n3. For each valid row, it checks if the English key exists in the current `en.yml` file.\n4. If the key exists, it adds the translation to the target locale's YAML structure.\n5. It logs various statistics and information about the import process.\n6. Finally, it writes the updated translations to the appropriate locale YAML file (e.g., `es.yml` for Spanish) and generates a metadata file with import details.\n\nThis translation import system allows for efficient management of translations across multiple locales.\n\n### How to Import New Locales\n\u003e ℹ️ **Note:**\n\u003e Ensure your CSV file contains at least two columns:\n\u003e - A 'key' column with the translation keys\n\u003e - A column for the target locale, matching the file's prefix (e.g., 'es' for Spanish)\n\u003e - Other columns in the CSV will be ignored by the import script\n\n**1.** Place your CSV file in the `tmp` directory of your Rails application.\n**2.** Name your CSV file using the following convention: `\u003clocale\u003e_import[_\u003ctimestamp\u003e].csv` (e.g., `es_import.csv` or `es_import_20230515120000.csv` for Spanish).\n   \u003e The timestamp in the filename is optional. If multiple files exist for a locale, the script will use the file with the latest timestamp.\n\n**3.** Run the rake task with the desired locale code:\n\n   ```\n   rake translations:import[\u003clocale\u003e]\n   ```\n\n   For example, to import Spanish translations:\n\n   ```\n   rake translations:import[es]\n   ```\n\n   or to import with **overwrite mode**:\n\n   ```\n   rake translations:import[es,true]\n   ```\n\n# Testing\n\n## Running tests (in the `app` subdirectory)\n\n* Tests: `bundle exec rspec`\n* E2E tests: `RUN_E2E_TESTS=1 bundle exec rspec spec/e2e/`\n* Accessibility scan: `./bin/pa11y-scan`\n* Dynamic security scan: `./bin/owasp-scan`\n* Ruby style linter: `bundle exec rubocop`\n* Ruby static security scan: `bundle exec rake brakeman`\n* Ruby dependency checks: `bundle exec rake bundler:audit`\n* JS dependency checks: `bundle exec rake npm:audit`\n\n## Manual Testing\nIf you're new to CBV, here's a summary of how to get started navigating the app.\n1. First, contact someone on the team to get you set up to log in.\n1. Follow the instructions in the Setup section to run locally, then go to `localhost:3000/sandbox/sso`\n1. The beginning of the workflow is to act as a caseworker to create an invitation. Start by signing in with your Nava credentials.\n1. Create an invitation for an applicant to start using the app (use any email, and don't worry -- it won't really send!)\n1. In your terminal session, navigate to the /app directory and run `rails c` to enter the irb prompt.\n1. At the irb prompt, run `CbvFlowInvitation.last.to_url`.\n1. Click the resulting link. Now you're ready to start acting as an applicant!\n1. Search for your employer. When you select one, the local page will show you some fake credentials at the very bottom of the screen. Use these to sign in.\n1. Finally, you should be able to complete the applicant flow, including looking at the PDF.\n1. To complete the caseworker flow, add `?is_caseworker=true` to the /cbv/summary.pdf path to see the PDF that gets sent (it's different from the one we send the applicant!)\n1. Note: You can switch to a different pilot partner (state) by going to the irb prompt and running `CbvFlow.last.update(client_agency_id: 'ma')`. Right now you can only pass it `ma` or `nyc`.\n\n## Pa11y Scan\n\nWhen new pages are added to the application, ensure they are added to `./.pa11yci` so that they can be scanned.\n\n## Coding style and linters\n\nTo enable automatic ruby linting and terraform formatting on every `git commit`, run the command `pre-commit install`.\n\nThis will run linters as configured by `.pre-commit-config.yml` before every commit. (For performance, it only runs linters on files that are being changed in the commit.)\n\nWe use the following linters:\n\n* **Ruby**: Rubocop, ErbLint\n* **JavaScript**: Prettier\n* **Markdown**: MarkdownLint\n* **GH Actions**: ActionLint\n* **Bash**: ShellCheck\n* **Terraform**: `terraform fmt`\n\n## CI/CD\n\nGitHub Actions are used to run all tests and scans as part of pull requests.\n\n## Vulnerability Scanning\n\nWe also run vulnerability scanners on every pull request. See [Vulnerability Management](/docs/infra/vulnerability-management.md) documentation for more details.\n\n## Running a production image locally\n\nTo debug locally an image built for deployment, see [the Running Built Images Locally runbook](/docs/app/runbooks/running-built-images-locally.md).\n\n\n# Deployment\n\n## Demo\n\nThis repo's `main` branch automatically deploys to our demo environment via [a GitHub action](/.github/workflows/cd-app.yml).\n\n## Production\n\nTo deploy to production, go to the repo's \"Actions\" tab on Github, [click \"Deploy App\"](https://github.com/DSACMS/iv-cbv-payroll/actions/workflows/cd-app.yml), and \"Run Workflow\".\n\n# Credentials and other Secrets\n\nTK\n\n## Non-secrets\n\nTK\n\n# Monitoring with New Relic\n\nThe [New Relic Ruby agent](https://docs.newrelic.com/docs/apm/agents/ruby-agent/getting-started/introduction-new-relic-ruby) has been installed for monitoring this application.\n\nThe config lives at `config/newrelic.yml`, and points to a [FEDRAMP version of the New Relic service as its host](https://docs.newrelic.com/docs/security/security-privacy/compliance/fedramp-compliant-endpoints/). To access the metrics dashboard, you will need to be connected to VPN.\n\n## Getting started\n\nTo get started sending metrics via New Relic APM:\n1. Add your New Relic license key to the Rails credentials with key `new_relic_key`.\n1. Optionally, update `app_name` entries in `config/newrelic.yml` with what is registered for your application in New Relic\n1. Comment out the `agent_enabled: false` line in `config/newrelic.yml`\n1. Add the [Javascript snippet provided by New Relic](https://docs.newrelic.com/docs/browser/browser-monitoring/installation/install-browser-monitoring-agent) into `application.html.erb`. It is recommended to vary this based on environment (i.e. include one snippet for staging and another for production).\n\n## Analytics\n\nDigital Analytics Program (DAP) code has been included for the Production environment, associated with GSA.\n\nIf Iv Cbv Payroll is for another agency, update the agency line in `app/views/layouts/application.html.erb`\n\n# Documentation\n\n## Repository Structure\nSee [CODEOWNERS.md](./CODEOWNERS.md) for some information on repo structure.\n\n## Documentation Index\n\nDocumentation is currently stored in CMS Confluence:\nhttps://confluenceent.cms.gov/display/SFIV/Consent-based+Verification+%28CBV%29+for+Payroll\n\n## Architectural Decision Records\n\nOur ADRs are stored in CMS Confluence: https://confluenceent.cms.gov/pages/viewpage.action?pageId=693666588\n\n# Contributing\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Community\n\nThe CBV team is taking a community-first and open source approach to the product development of this tool. We believe government software should be made in the open and be built and licensed such that anyone can download the code, run it themselves without paying money to third parties or using proprietary software, and use it as they will.\n\nWe know that we can learn from a wide variety of communities, including those who will use or will be impacted by the tool, who are experts in technology, or who have experience with similar technologies deployed in other spaces. We are dedicated to creating forums for continuous conversation and feedback to help shape the design and development of the tool.\n\nWe also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents, and offer support to community members with a wide variety of backgrounds and skillsets.\n\n## Community Guidelines\nSee [COMMUNITY_GUIDELINES.md](./COMMUNITY_GUIDELINES.md).\n\n## Governance\n\nSee [GOVERNANCE.md](./GOVERNANCE.md)\n\n## Feedback\n\nIf you have ideas for how we can improve or add to our capacity building efforts and methods for welcoming people into our community, please let us know by sending an email to: ffs at nava pbc dot com. If you would like to comment on the tool itself, please let us know by filing an **issue on our GitHub repository.**\n\n## Policies\n\n### Open Source Policy\n\nWe adhere to the [CMS Open Source\nPolicy](https://github.com/CMSGov/cms-open-source-policy). If you have any\nquestions, just [shoot us an email](mailto:opensource@cms.hhs.gov).\n\n### Security and Responsible Disclosure Policy\n\n\u003c!-- markdown-link-check-disable --\u003e\n*Submit a vulnerability:* Unfortunately, we cannot accept secure submissions via\nemail or via GitHub Issues. Please use our website to submit vulnerabilities at\n[https://hhs.responsibledisclosure.com](https://hhs.responsibledisclosure.com/).\nHHS maintains an acknowledgements page to recognize your efforts on behalf of\nthe American public, but you are also welcome to submit anonymously.\n\u003c!-- markdown-link-check-enable --\u003e\n\nFor more information about our Security, Vulnerability, and Responsible Disclosure Policies, see [SECURITY.md](SECURITY.md).\n\n### Public domain\n\nThis project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/) as indicated in [LICENSE](LICENSE).\n\nAll contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.\n\n# Core Team\n\nSee [CODEOWNERS.md](./CODEOWNERS.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsacms%2Fiv-cbv-payroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsacms%2Fiv-cbv-payroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsacms%2Fiv-cbv-payroll/lists"}