{"id":13623422,"url":"https://github.com/aws-samples/aws-codepipeline-stepfunctions","last_synced_at":"2025-04-15T14:33:00.910Z","repository":{"id":26133632,"uuid":"105296100","full_name":"aws-samples/aws-codepipeline-stepfunctions","owner":"aws-samples","description":"This project shows how to integrate AWS CodePipeline and AWS Step Functions state machines. The integration enables developers to build much simpler CodePipeline actions that perform a single task and to delegate the complexity of dealing with workflow-driven behavior associated with that task to a proper state machine engine. As such, developers will be able to build more intuitive pipelines and still being able to visualize and troubleshoot their pipeline actions in detail by examining the state machine execution logs.","archived":false,"fork":false,"pushed_at":"2024-04-10T09:57:56.000Z","size":456,"stargazers_count":85,"open_issues_count":13,"forks_count":48,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-08-01T21:56:48.451Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2017-09-29T16:50:06.000Z","updated_at":"2024-04-02T15:44:31.000Z","dependencies_parsed_at":"2024-01-14T06:54:25.981Z","dependency_job_id":"a3039ad7-5b7b-45b5-a71f-5fa147c9e3ac","html_url":"https://github.com/aws-samples/aws-codepipeline-stepfunctions","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-codepipeline-stepfunctions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-codepipeline-stepfunctions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-codepipeline-stepfunctions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-codepipeline-stepfunctions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-samples","download_url":"https://codeload.github.com/aws-samples/aws-codepipeline-stepfunctions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223677608,"owners_count":17184509,"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-08-01T21:01:31.650Z","updated_at":"2024-11-08T11:30:47.915Z","avatar_url":"https://github.com/aws-samples.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\nWelcome to the __aws-codepipeline-stepfunctions__ project on AWS Labs! \n\nHow about delegating complex CodePipeline tasks to a proper state machine and keeping your pipeline clean and easy to understand? \n\n![approach-overview](pipeline/docs/codepipeline_statemachine.png)\n\nThis project shows you how to integrate AWS CodePipeline and AWS Step Functions state machines. The integration enables developers to build much simpler CodePipeline actions that perform a single task and to delegate the complexity of dealing with workflow-driven behavior associated with that task to a proper state machine engine. As such, developers will be able to build more intuitive pipelines and still being able to visualize and troubleshoot their pipeline actions in detail by examining the state machine execution logs.\n\n## Project structure\n\n* __app/__ - contains a CloudFormation template that represents the application being deployed via CodePipeline/Step Functions.\n\n* __pipeline/codepipeline__ - CodePipeline resources\n\n* __pipeline/statemachines__ - Step Functions resources including the _Deploy_ state machine\n\n* __pipeline/local_modules__ - required local npm modules\n\n* __pipeline/docs__ - project's documentation artifacts\n\n## Required Software\n\nPlease install the following software in your local workstation before proceeding:\n\n* [Git client](https://git-scm.com/downloads)\n\n* [AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/installing.html) (version 1.11.170 or greater)\n\n* Configure your AWS credentials (access keys, AWS region, etc). At a minimum your credentials should allow you to create and manipulate resources associated withe the following AWS services: Amazon S3, AWS CodeCommit, AWS CodePipeline, AWS Lambda, AWS StepFunctions, and AWS IAM.\n\n```bash\naws configure\n```\n\n* Install [npm](https://www.npmjs.com/get-npm)\n\nIf you plan to develop and contribute to the project it's a good idea to use SAM Local:\n\n* [AWS SAM Local](https://github.com/awslabs/aws-sam-local)\n\n## Instructions\n\n### Make all scripts executable\n\nFrom the project's root directory, type:\n\n```bash\nchmod u+x **/*.sh\n```\n\n### Install required NPM modules\n\nFrom the project's root directory, type:\n\n```bash\n  cd pipeline/\n  install_dependencies.sh\n```\n\n### Deploy Resources\n\n* Clone this project in your local workstation (git clone ...)\n\n* If you wish to use your _default_ AWS profile skip this step, otherwise open script file _config.sh_ and enter your profile using variable _AWS\\_PROFILE_.\n\n```bash\nvi pipeline/config.sh\n```\n\nImportant: Make sure the AWS profile chosen uses an AWS region that supports AWS Step Functions [(check here)](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).\n\n* From the project's root directory run:\n\n```bash\n  cd pipeline/\n  ./bootstrap.sh\n```\n\nThe _bootstrap_ script will create all necessary resources including:\n\n* S3 buckets for CodePipeline, Lambda and the State Machine\n* Several Lambda functions for CodePipeline and Step Functions \n* The CodeCommit repository\n* The Step Functions state machine\n* The CodePipeline pipeline\n\n### Push Code and Trigger CodePipeline\n\nOnce the bootstrap script completes, open the AWS Console and check the various resources created for you including a CodeCommit repository, a CodePipeline pipeline, a Step Functions state machine, three S3 buckets, and IAM roles. Note that the CodePipeline pipeline is in a failing state since the CodeCommit repository does not have any code. The next step will be to push code to the CodeCommit repository which will cause the pipeline to start processing the changes. \n\nLet's add code to the repository.\n\n* Using the AWS Console, navigate to the CodeCommit repository created for you\n\n* Click on \"Connect\" or follow [these instructions](http://docs.aws.amazon.com/codecommit/latest/userguide/how-to-connect.html) to set up credentials to your IAM user to allow you to clone the CodeCommit repository (via SSH or HTTPS). \n\n* Back in your local workstation. From the project's root directory, type:\n\n```bash\n  cd app/\n  git init \u0026\u0026 git add --all\n  git commit -m \"initial commit\"\n  git remote add codecommit [YOUR-CODECOMMIT-REPO-CLONE-URL]\n  git push codecommit master\n```\n\nThis will push code into the CodeCommit repository and trigger the CodePipeline pipeline after a few seconds. \n\nOpen the CodePipeline Console and follow the execution of the pipeline. The _Source_ pipeline action will simply load the source code from CodeCommit into an S3 bucket. The _Deploy_ action invokes the _StateMachineTriggerLambda_ Lambda function which, in turn, fetches the state machine input parameters from a file in S3 and triggers the state machine (see figure above for further details). The state machine starts executing while the _StateMachineTriggerLambda_ Lambda sends a continuation token to CodePipeline and terminates. Seconds later, the _StateMachineTriggerLambda_ Lambda is invoked again by CodePipeline. The Lambda will check whether the state machine execution has completed and, if that's the case, it will notify the pipeline that the pipeline action succeeded. If otherwise the state machine has failed, the Lambda will send a failure response to the pipeline action interrupting the pipeline execution. The _StateMachineTriggerLambda_ Lambda fully decouples the pipeline from the state machine.\n \nFor further details please read our [AWS DevOps Blog post](https://aws.amazon.com/blogs/devops/using-aws-step-functions-state-machines-to-handle-workflow-driven-aws-codepipeline-actions/)\n\n## Contributing\n\nHere are a few details you need to know if you wish to contribute to this project.\n\n### Running Locally\n\nPlease use [AWS SAM Local](https://github.com/awslabs/aws-sam-local) to run and debug Lambda functions locally. It is really useful and saves a lot of time. A script named _run\\_local.sh_ is available under _pipeline/codepipeline_ and _pipeline/statemachine/deploy_ for convenience.\n\nIn order to run Lambda functions locally, SAM local requires that test events are passed as input to the Lambda functions. Sample test events are provided under _test\\_events_/. Important: the provided test events might contain account-specific parameters that need to be adjusted.\n\nHere is an example of how to invoke the _CreateStackStateMachineTask_ Lambda function:\n\n```bash\n  cd pipeline/statemachines/deploy\n  ./run_local.sh CreateStackStateMachineTask create_stack\n```\n\nNote that template _state\\_machine\\_template.yaml_ and test event file _test\\_events/event\\_create\\_stack.json_ are referenced within the script.\n\n### Modifying Local Modules\n\nIf you plan to make changes to local modules (under _pipeline/local\\_modules) keep in mind that this requires updating the modules that depend on these local modules.\n\nThis can be accomplished by running these scrips:\n\n```bash\n # pack changes made to local modules\n cd pipeline/local_modules\n ./pack_modules.sh\n   \n # update codepipeline local modules references\n cd pipeline/codepipeline\n ./install_modules.sh\n   \n # update statemachines/deploy local module references\n cd pipeline/statemachines/deploy\n ./install_modules.sh\n```\n\nHave fun and contribute!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Faws-codepipeline-stepfunctions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-samples%2Faws-codepipeline-stepfunctions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Faws-codepipeline-stepfunctions/lists"}