{"id":21827591,"url":"https://github.com/dieproduktmacher/serverless-env-generator","last_synced_at":"2025-04-14T05:43:06.211Z","repository":{"id":22029739,"uuid":"93610337","full_name":"DieProduktMacher/serverless-env-generator","owner":"DieProduktMacher","description":"A Serverless 1.x plugin to manage environment variables with YAML and turn them into a .env file on deployment. Supports encryption with KMS, multiple stages and custom profiles.","archived":false,"fork":false,"pushed_at":"2022-12-10T22:28:09.000Z","size":1331,"stargazers_count":31,"open_issues_count":21,"forks_count":11,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2024-04-14T10:53:24.020Z","etag":null,"topics":["aws","aws-kms","credentials","encryption","environment-variables","serverless-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/DieProduktMacher.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}},"created_at":"2017-06-07T08:18:29.000Z","updated_at":"2023-04-28T11:46:34.000Z","dependencies_parsed_at":"2023-01-14T07:00:25.488Z","dependency_job_id":null,"html_url":"https://github.com/DieProduktMacher/serverless-env-generator","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DieProduktMacher%2Fserverless-env-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DieProduktMacher%2Fserverless-env-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DieProduktMacher%2Fserverless-env-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DieProduktMacher%2Fserverless-env-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DieProduktMacher","download_url":"https://codeload.github.com/DieProduktMacher/serverless-env-generator/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830420,"owners_count":21168272,"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":["aws","aws-kms","credentials","encryption","environment-variables","serverless-plugin"],"created_at":"2024-11-27T18:13:39.581Z","updated_at":"2025-04-14T05:43:06.188Z","avatar_url":"https://github.com/DieProduktMacher.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Serverless Env Generator Plugin\n=======\n\n[![License][ico-license]][link-license] [![NPM][ico-npm]][link-npm] [![Build Status][ico-build]][link-build] [![Requirements Status][ico-requirements]][link-requirements] [![Coverage Status][ico-coverage]][link-coverage]\n\n[ico-coverage]: https://coveralls.io/repos/github/DieProduktMacher/serverless-env-generator/badge.svg?branch=develop\n[link-coverage]: https://coveralls.io/github/DieProduktMacher/serverless-env-generator?branch=master\n\nThis plugin automatically creates a *.env* file during deployment by merging environment variables from one or more YAML files. During runtime these variables can then be loaded into *process.env* using *dotenv*.\n\nFor a brief introduction, read our blogpost about [introducing serverless-env-generator](http://www.dieproduktmacher.com/introducing-serverless-env-generator/).\n\n\n### Key features:\n\n- Support for multi-stage configurations and custom profiles\n- Value of environment variables can be encrypted with AWS KMS, allowing teams to manage sensitive information in git.\n- By using KMS, access to secrets can be controlled with IAM. We recommend to create one KMS key per serverless-profile, so you can limit access to credentials to deployment privileges.\n- During deployment a temporary .env file is created and uploaded to Lambda by merging and decrypting values of your environment YAML files.\n- Environment variables can be loaded with *dotenv* at startup in Lambda without delays from KMS.\n- Supports *serverless-local-dev-server* and *serverless offline* for local development.\n\n\n\n### Notes\n\nPlease note that the uploaded *.env* file contains secrets in cleartext. Therefore we recommend to use [Serverless Crypt](https://github.com/marcy-terui/serverless-crypt) for critical secrets. This tool aims to strike a balance between storing secrets in plaintext in Lambda environment variables and having to decrypt them at runtime using KMS.\n\nFurthermore the tool does not support environment variables generated by Serverless. We recommend to set these variables directly in each functions configuration in *serverless.yml*.\n\nWhen used with *serverless-local-dev-server* your environment variables are directly loaded into *process.env*. No *.env* file is created to make sure that your local development and deployment tasks do not interfere :-)\n\nThis package requires node \u003e= 8.0.\nDue to the reliance on KMS, encryption is only supported for AWS.\n\nThe `.env.local` file in the project root is here only for the tests.\n\n# Table of Contents\n\n- [Requirements](#requirements)\n- [Getting Started](#getting-started)\n- [Commands](#commands)\n- [YAML File Structure](#yaml-file-structure)\n- [Usage with the serverless-plugin-webpack](#usage-with-the-serverless-plugin-webpack)\n- [Contribute](#contribute)\n\n\n# Requirements\n\n- node \u003e= 8.0\n- serverless \u003e= 1.14\n- [See below for usage with serverless-plugin-webpack](#usage-with-the-serverless-plugin-webpack)\n\n\n# Getting Started\n\n### 1. Install the plugin and dotenv\n\n```sh\nnpm install dotenv --save\nnpm install serverless-env-generator --save-dev\n```\n\n### 2. Create a key on KMS\n\nSee: https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html\n\nPlease make sure to create the KMS key in the same region as your deployment.\n\nFor aliases we recommend to use the service name, for administration privileges no user (your AWS account has full permissions by default) and for usage privileges \"serverless-admin\" to link access permissions to deployment permissions.\n\n\n### 3. Add the plugin to your serverless configuration file\n\n*serverless.yml* configuration example:\n\n```yaml\nprovider:\n  name: aws\n  runtime: nodejs8.10\n\nfunctions:\n  hello:\n    handler: handler.hello\n\n# Add serverless-env-generator to your plugins:\nplugins:\n  - serverless-env-generator\n\n# Plugin config goes into custom:\ncustom:\n  envFiles: #YAML files used to create .env file\n    - environment.yml\n  envEncryptionKeyId: #KMS Key used for encrypting values\n    dev: ${env:AWS_KMS_KEYID} #Key used for development-stage\n```\n\n### 4. Add the .env file to your .gitignore\n\nAs the generated *.env* file contains the secrets in cleartext,\nmake sure that it will never be checked into git!\n\n*.gitignore* code example:\n\n```\n.env\n```\n\n\n### 5. Add variables to your environment YAML file\n\nCommand example:\n\n```sh\nserverless env --attribute name --value \"This is not a secret\"\nserverless env --attribute secret_name --value \"This is a secret\" --encrypt\n```\n\n### 6. Write your function\n\nNote that the *.env* file is automatically created when you deploy your function,\nso you can just load those variables with dotenv 🎉\n\nCode example:\n\n```js\nrequire('dotenv').config() // Load variables from .env file\n\nmodule.exports.hello = (event, context, callback) =\u003e {\n  const response = {\n    statusCode: 200,\n    body: JSON.stringify({\n      message: process.env.secret_name,\n      input: event\n    })\n  }\n  callback(null, response)\n}\n```\n\n### 7. Deploy \u0026 test your function\n\nCommand example:\n\n```sh\nserverless deploy\nserverless invoke -f $FUNCTION_NAME\n```\n\nResult example:\n\n```\n{\n    \"body\": \"{\\\"input\\\": {}, \\\"message\\\": \\\"This is a secret\\\"}\",\n    \"statusCode\": 200\n}\n```\n\n\n# Commands\n\nYou can use these commands to modify your YAML environment files.\n\nIf no stage is specified the default one as specified in *serverless.yml* is used.\n\n## Viewing environment variables\n\nUse the following commands to read and decrypt variables from your YAML environment files:\n\n### List variables\n\n```sh\nserverless env\nserverless env --stage $STAGE\n```\n\n### View one variable\n\n```sh\nserverless env --attribute $NAME\nserverless env --attribute $NAME --stage $STAGE\n\n#shorthand:\nsls env -a $NAME\nsls env -a $NAME -s $STAGE\n```\n\n### Decrypt variables\n\n```sh\nserverless env --decrypt\nserverless env --attribute $NAME --decrypt\nserverless env --attribute $NAME --stage $STAGE --decrypt\n\n#shorthand:\nsls env -a $NAME --decrypt\nsls env -a $NAME -s $STAGE -d\n```\n\n## Setting environment variables\n\nUse the following commands to store and encrypt variables in your YAML environment files:\n\nNote that variables are stored to the first file listed in *envFiles*.\n\n### Set a variable\n\n```sh\nserverless env --attribute $NAME --value $PLAINTEXT\nserverless env --attribute $NAME --value $PLAINTEXT --stage $STAGE\n\n#shorthand:\nsls env -a $NAME -v $PLAINTEXT\nsls env --a $NAME -v $PLAINTEXT --s $STAGE\n```\n\n### Set and encrypt a variable\n\n```sh\nserverless env --attribute $NAME --value $PLAINTEXT --encrypt\nserverless env --attribute $NAME --value $PLAINTEXT --stage $STAGE --encrypt\n\n#shorthand:\nsls env -a $NAME -v $PLAINTEXT -e\nsls env -a $NAME -v $PLAINTEXT -s $STAGE -e\n```\n\n\n# YAML File Structure\n\nEnvironment variables are stored in stage-agnostic YAML files,\nwhich are then merged into a .env file on deployment.\n\nFile example:\n\n```yaml\ndev: #stage\n    foo: bar #cleartext variable\n    bla: crypted:bc89hwnch8hncoaiwjnd... #encrypted variable\n\nproduction:\n    foo: baz\n    bla: crypted:ncibinv0iwokncoiao3d...\n```\n\nYou can create additional YAML environment files, for example to include variables that are dynamically generated.\nJust add them to the *envFiles* in your *serverless.yml*.\n\n# Usage with the `serverless-plugin-webpack`\n\nIn case you are also using the [`serverless-plugin-webpack`](https://github.com/goldwasserexchange/serverless-plugin-webpack) there are some caveats:\n\n## 1. Plugin order in `serverless.yml'\n\nYou have to place `serverless-env-generator` before the `serverless-plugin-webpack` in the `serverless.yml`\n\n```yaml\n# serverless.yml\nplugins:\n  - serverless-env-generator\n  - serverless-plugin-webpack\n```\n\n## 2. Additional `dotenv-webpack`\n\nYou need to have the [`dotenv-webpack`](https://github.com/mrsteele/dotenv-webpack) plugin installed:\n\n```sh\nnpm install dotenv-webpack --save-dev\n```\n\nand configured:\n\n```javascript\n// webpack.config.js\nconst Dotenv = require('dotenv-webpack')\nmodule.exports = {\n  // ...\n  plugins: [\n    // ...\n    new Dotenv()\n  ]\n}\n```\n\n# Contribute\nAnyone is more than welcome to contribute to the serverless-env-generator plugin. Here just a few things to consider when doing so:\n\n- this project uses yarn as a package manager\n- make sure to pass all tests (run *yarn test*)\n- you can add your local *serverless-env-generator* version to other projects: yarn add --dev file:/../serverless-env-generator\n\n# License \u0026 Credits\n\nLicensed under the MIT license.\n\nCreated and maintained by [DieProduktMacher](http://www.dieproduktmacher.com).\n\nInspired by [Serverless Crypt](https://github.com/marcy-terui/serverless-crypt).\n\n[ico-license]: https://img.shields.io/github/license/dieproduktmacher/serverless-env-generator.svg\n[ico-npm]: https://img.shields.io/npm/v/serverless-env-generator.svg\n[ico-build]: https://travis-ci.org/DieProduktMacher/serverless-env-generator.svg?branch=develop\n[ico-contributors]: https://img.shields.io/github/contributors/dieproduktmacher/serverless-env-generator.svg\n[ico-requirements]: https://requires.io/github/DieProduktMacher/serverless-env-generator/requirements.svg?branch=master\n\n[link-license]: ./LICENSE.txt\n[link-npm]: https://www.npmjs.com/package/serverless-env-generator  \n[link-build]: https://travis-ci.org/DieProduktMacher/serverless-env-generator\n[link-contributors]: https://github.com/DieProduktMacher/serverless-env-generator/graphs/contributors\n[link-requirements]: https://requires.io/github/DieProduktMacher/serverless-env-generator/requirements/?branch=master","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdieproduktmacher%2Fserverless-env-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdieproduktmacher%2Fserverless-env-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdieproduktmacher%2Fserverless-env-generator/lists"}