GitHub CodePipeline example
CD Pipelines define the application to be deployed using an "Infrastructure as Code" (IaC) strategy, and in our case we use AWS CloudFormation as our IaC tool. The definition of the application to be deployed can be found in the
Moreover the pipeline itself is defined in code, also using CloudFormation, and its definition is the
pipeline.yaml template. The benefits of defining a CD pipeline in versioned source are the same as those for defining an application's deployment in source - automatibilty, visibility, etc.
We define the pipeline in the same repository as the application itself - this is possible since AWS CodePipeline provides CD as a service - we do not need to manage any pipeline servers. Keeping the CD definition closely tied to the application definition allows us to make infrastructural changes quickly and simply.
GitHub is an extremely popular location to host source code for applications, and this example uses GitHub as its source code location. We define the integration between AWS and GitHub solely within the Pipeline's template - no manual use of the AWS Console or CodePipeline API are required.
As part of the GitHub integration we make use of CodePipeline's "GitHub Webhook" feature to allow for executions that trigger more quickly, and that allow source event filtering.
How to create the pipeline
Fork this repository to your own GitHub repository
GitHubRepodefault parameter values in
pipeline.yamlfor your fork.
Create a new GitHub personal access token for this application. See here for how to do this - CodePipeline needs just the
reposcope permissions. I recommend you name the token for this particular pipeline, at least to get started, and that you store the token somewhere safe, like a password manager.
⚠️The user associated with the personal access token above MUST have administrative rights for the Github repo - either by being an owner of the repo, or having been granted admin privs. Simply having write access is not sufficient, because this template attempts to create a webhook in Github. If your user has insufficient privileges the pipeline creation process will fail, but will create an stranded / undeletable version of your application stack.
By default the application CloudFormation stack will be named
github-codepipeline-app, and the CodePipeline stack will be named
github-codepipeline. If / when you want to change these then update the following files, looking for references to
Commit all your changes to source control
Now from a terminal run the following (this assumes the AWS CLI is installed and configured). Make sure the terminal is configured to use the AWS region where you want the pipeline itself to run (or override using the
--regionflag), and that it is configured to use the account where the pipeline and application will run. Provide the GitHub token value that you created in step 3.
$ ./create-pipeline.sh YOUR-GITHUB-TOKEN
Once you've run this last command then watch both the CloudFormation and then CodePipeline consoles to evaluate whether the process has been successful. You should have two new CloudFormation stacks - one for the pipeline and one for the application, and you should be able to see a new Pipeline in CodePipeline.
To test everything, after the pipeline has successfully completed it's first run, check the S3 console to see whether the new application bucket (as defined in
application.yaml) has been created.
How to update the pipeline
When you need to update the application code or structure (as defined in
application.yaml), then simply pushing your changes to source control will be sufficient - CodePipeline references these files from source on every pipeline run.
If you need to change the structure of the CodePipeline itself then run
update-pipeline.sh with the same GitHub token argument that you ran with
create-pipeline.sh. If you no longer have the token then create a new one and use that.
- Delete the application stack
- Delete the artifact bucket created by the pipeline
- Delete the pipeline stack
Questions, Comments, Additions, Suggestions
If your company is looking for help using CodePipeline, CloudFormation, or architecture using AWS then please contact us at Symphonia.
- Refine IAM permissions in pipeline.yaml