-
Notifications
You must be signed in to change notification settings - Fork 3
GitHub Workflows
GitHub Actions is a CI/CD platform that can be used in any GitHub repository. It’s organized at the highest level into workflows. Each workflow is defined in its own file located in .github/workflows/. Each workflow file defines one or more jobs to run and when to run them.
This section will detail each of the project’s workflows. Some may require a fair amount of detail, others may be simple and obvious. For sake of portability, each will be documented in its own file in this documentation site.
If you see any gaps, please let us know! GitHub Actions is really the production floor of our product, and its important to have complete documentation.
Reflect our active Security Hub findings in Jira.
CMS projects deployed in AWS are required to resolve Security Hub findings according to the following schedule:
- Critical vulnerabilities within 15 days from discovery
- High vulnerabilities within 30 days from discovery
- Moderate (MEDIUM) vulnerabilities within 90 days from discovery
- Low vulnerabilities within 365 days from discovery
The security-hub-jira-sync workflow exists to get Security Hub findings in a project’s AWS account(s) into Jira and in front of the developers equipped to resolve them. The workflow works by running the macpro-security-hub-sync npm package on a cron, scheduled for every other hour during business hours. Please see the npm packages documentation for more details. In short: when the package is run, the master branch’s AWS account is scanned for SecHub findings, those finding types get issues created in Jira, and any resolved SecHub issues that have a Jira issue have their issue closed.
The security hub workflow is unique, in that it should ideally only be run by one project per AWS account. Since security hub findings are scoped to the account, and since we can have many projects deployed to a given account, multiple instances of the security hub workflow running is not ideal. It is rather harmless if two projects in the same account were both running the workflow, but it’s best avoided.
To that end, a new project based off this repo will not run this workflow automatically. There is an environment variable flag that must be set before the job will run.
To enable the security-hub-jira-sync workflow, set a repository variable named ‘ENABLE_SECURITY_HUB_SYNC’ to any value. The existence of the variable is what is checked, not its value. To set a GitHub actions secret, follow the same steps as creating an Actions secret, but look for a tab that says ‘Variables’. These function just like secrets in their scope, but are unencrypted.
Per the macpro-security-hub-sync docs, you’ll need to create username and token secrets for a jira user. The token is more accurately called a Personal Access Token (PAT) in Jira, and can be created by logging into Jira in a web browser and following these instructions.
On MACPro, we use a service user; you probably should, too. If you’re on MACPro, you may be able to leverage our existing service user; reach out to [email protected] or Nathan O’Donnell about possible access.
In the workflow definition, there are hardcoded values for JIRA_HOST and JIRA_PROJECT. These values are what all projects on MACPro should use, so we’ve kept it simple and put them directly in the file. If you’re not on MACPro or need to change these values, make the appropriate updates to the file.
Some Jira projects require certain fields to be set for issues to be created. This is the case with MACPro’s Jira installation. We have two fields that must be set. These fields are set in the run script. You’ll note two lines that begin with ‘customfield_’. Unfortunately, we must set the actual id and value of the custom field as Jira expects it. These ids will vary from instance to instance, even if the field name is the same. Despite our best efforts, the complexity and number of options and allowances when setting custom fields makes it incredibly difficult to have a more user friendly experience; you must find the customfield id’s for the values you must set. If you’re on MACPro and use our Jira, these are the field values you need, which map to Working Team and Product Supported. If you’re not on MACPro and using a different Jira, trial and error is usually fine; the package will surface the Jira API error as it says ‘customfield_1234 is not set, Product Supported is not set’. In other words, you can look carefully at the fail output to find the id names. Alternatively, you may also query the Jira API and be more exact about it.
In any event, you probably want to update the Working Team from Platform Team to your team name.
On MACPro, we typically use three separate levels of AWS accounts for each project:
- dev account: this holds the default branch (master) enviroment along with all ephemeral branches/environments.
- impl account: this holds the val environment built from the val branch.
- production account: this holds the production environment built from the production branch.
Obviously, the sechub workflow needs to authenticate and talk to AWS. It gets the arn of the role to assume from a github secret. What you should know is: the scheduled/crond workflow will only kick off on the default/master branch; this is how cron’d workflows behave. This means that your workflow will only automatically manage findings in Jira for the dev aws account. If/when you’d like to scan the impl/production accounts for findings, you may manually run the security hub workflow (workflow_dispatch action) from the GitHub UI. When triggering a build, it will ask off of which branch it should run; you may select val or production as you wish.
You might be wondering: why can’t we work around this? Good question; and the answer is ‘we could’. But there are bigger obstacles to automated val/production runs than the cron behavior. For instance, our OIDC role’s trust policy pattern will only allow workflows run off of the true val or production branch to assume the aws service role, respectivelly. To add to the issues, if we were to build a mechanism to trigger security hub sync off of val or production so we could assume the role, GitHub would require an administrator to approve the workflow’s access to the Environment holding the role arn before it would be allowed to continue. This is all by design, and all very good ideas. By design, having automatic and unattended builds run against val and production is not possible, or at least very difficult.
In summary: you will only get automatic sec hub scanning for the dev account, which should go a long way to keeping the higher environments safe from vulnerabilities brought about by vulnerable code. Scanning impl and production must be done by manually running the workflow ad hoc, which can be accomplished through the GitHub UI.
Automatically links Pull Requests to Jira Issues mentioned in the PR body.
The macpro-mako project uses GitHub Pull Requests to review and merge and code change. A GitHub pull request is a feature that allows developers to propose changes to a project’s codebase. When a developer wants to suggest changes to a project, they create a pull request which includes the code changes they’ve made. The pull request then allows other developers to review the proposed changes, discuss any potential issues, and ultimately merge the changes into the main codebase.
The macpro-mako project uses Jira to plan, schedule, and track development work items.
As a general rule, most pull requests should be related to a Jira Issue. In fact our PR template has a section where you may list related issues.
The auto-create-jira-comment workflow is meant to scan pull requests for Jira Issue links; any issues that it finds receives a new comment “This issue was referenced on (link to pull request)”. If it finds no issue links in the PR, nothing happens. If it finds one, two, or ‘n’ issues, they all receive that same “This issue was referenced…” comment. While this workflow will not automatically close issues in Jira, it works to create that link between work item and pull request, provided the team can add Jira Issue links to PRs.
The workflow file expects two secrets to be set, JIRA_USERNAME and JIRA_TOKEN. IF they’re not set, the workflow will not fail, but it will be unable to comment on Jira issues.
You’ll need to create username and token secrets for a jira user. The token is more accurately called a Personal Access Token (PAT) in Jira, and can be created by logging into Jira in a web browser and following these instructions.
On MACPro, we use a service user; you probably should, too. If you’re on MACPro, you may be able to leverage our existing service user; reach out to [email protected] or Nathan O’Donnell about possible access.
Load these values for JIRA_USERNAME and JIRA_TOKEN into the repository’s actions secrets, and the workflow functionality will be operational.
In the workflow definition, there is a hardcoded value for JIRA_BASE_URL. This is used to more precisely find Jira issue links. As this value is the same for MACPro projects, it was hardcoded to reduce configuration burden. But if your project uses a different Jira than the one listed, update this value to your Jira base url.
Deploys the stage
This GitHub workflow deploys an application to AWS and performs various tests and checks on the resources deployed. It consists of several jobs:
- init: This job validates the name of the branch and ensures that it adheres to the naming convention used by the Serverless Framework.
- deploy: This job deploys the application to AWS using the Serverless Framework. It checks out the source code, configures AWS credentials, and deploys the application using the run deploy command.
- test: This job runs automated tests on the deployed application. It checks out the source code, configures AWS credentials, and runs the tests using the run test command.
- cfn-nag: This job performs a static analysis of the AWS CloudFormation templates used by the application. It checks out the source code, configures AWS credentials, and uses the stelligent/cfn_nag action to analyze the templates.
- resources: This job retrieves information about the resources deployed to AWS by the application. It checks out the source code, configures AWS credentials, and uses the aws cloudformation list-stack-resources command to retrieve information about the resources
- release: This job creates a release of the application. It checks out the source code, configures AWS credentials, and creates a GitHub release with the artifacts produced by the test, cfn-nag, and resources jobs.
- Name: Deploy
- Triggers: This workflow is triggered on every push to any branch, except for branches that start with “skipci”.
- Concurrency: This workflow is limited to one concurrent run per branch.
-
Environment Variables:
- STAGE_NAME: The name of the deployment stage. This is set to the name of the branch by default.
-
Permissions:
-
id-token: write -
contents: write -
issues: write -
pull-requests: write
-
-
Jobs:
-
init:
- Runs on: Ubuntu 20.04
-
Steps:
- Validate the stage name
-
deploy:
- Runs on: Ubuntu 20.04
- Needs: init
-
Environment:
STAGE_NAME -
Steps:
- Checkout the source code
- Use the
aws-actions/configure-aws-credentialsaction to configure AWS credentials - Deploy the application using the run deploy command
-
test:
- Runs on: Ubuntu 20.04
- Needs: deploy
-
Environment:
STAGE_NAME -
Steps:
- Checkout the source code
- Use the
aws-actions/configure-aws-credentialsaction to configure AWS credentials - Run automated tests using the run test command
-
cfn-nag:
- Runs on: Ubuntu 20.04
- Needs: deploy
- Environment:
STAGE_NAME - Steps:
- Checkout the source code
- Use the
aws-actions/configure-aws-credentialsaction to configure AWS credentials - Use the
stelligent/cfn_nagaction to perform a static analysis of the AWS CloudFormation templates
-
resources:
- Runs on: Ubuntu 20.04
- Needs: deploy
-
init:
A work of the MACPRO Platform Team for the Centers for Medicare & Medicaid Services.