Efforts to Improve Deploy Traceability to Multiple Environments Utilizing GitHub and JIRA

Introduction

I am Kanaya, a member of the KINTO FACTORY project, a service that allows you to renovate and upgrade your car. In this article, I will introduce our efforts to improve Deploy Traceability to Multiple Environments Utilizing GitHub and JIRA. Last time, I also wrote an article related to Remote Mob Programming in the Payments Team.

Background and Challenges

I joined the KINTO FACTORY project from the latter half of the development process. I was assigned as the frontend team leader for the e-commerce site project, and during my time in charge, I noticed the following issues:

1. GitHub Issues, JIRA, and Excel are used for task management, making progress difficult to manage
2. Difficult to track which tasks are deployed in which environment
3. Troublesome to generate release notes when deploying to a test environment

Excel WBS and Gantt chart example

First, managing progress was difficult. At the time I joined the project, there were three types of task management tools: GitHub Issues, JIRA, and Excel WBS and Gantt charts, all of which were in use. This lack of centralized control of necessary information made it difficult to manage schedules and tasks. Second, it was difficult to track which tasks are deployed in which environment. During development, there were two target environments for deployment (a development environment and a test environment), making it challenging to know which environment the task under development had already been deployed to. Lastly, Troublesome to generate release notes when deploying to a test environment. Since the test environment was used for testing not only by us engineers, but also by the QA team responsible for quality assurance, we needed to communicate when and which content was deployed to it. We used to create release notes as a communication method, but writing them each time took about 5 minutes and was quite stressful.

Our goal was to improve deployment traceability to address these issues. At least issue 2 and 3 (environment-specific deployment management issues, release note generation issues) are expected to be resolved. In addition, we aim to resolve issue 1 (difficulty in managing progress) by changing the way of work, as described later.

Policy to Enhance Deployment Traceability

First of all, traceability is described in DevOps technology: Version Control | DevOps Capabilities as follows. Among these, it is required that differences between multiple environments are either avoided or quickly identified once they occur. Note that version control of all dependencies can be managed in package.json, package-lock.json of npm for the frontend, so I'll skip that here.

No matter which environment is chosen, it is essential to quickly and accurately determine the versions of all dependencies used to create the environment. Additionally, the two versions of the environment should be compared to understand the changes between them.

As a policy to improve traceability to manage which tasks are deployed to which environments, we did the following:

1. Manage all tasks and deployments with JIRA
2. Rely on automatic generation of release notes

Manage all tasks and deployments with JIRA

JIRA has a feature to view development information for an issue. Since we know the status of code, reviews, builds, and deployments, we decided to consolidate all development information into JIRA.

To integrate JIRA and GitHub, the following steps are required:

1. Set up for JIRA and GitHub integration
2. Include the JIRA ticket number in the branch name to connect the JIRA ticket with the GitHub pull request
3. Set up the environment during deployment with GitHub Actions

The second step was the part left to the work of each engineer. In asking each engineer to include the JIRA ticket number, we have decided to eliminate the use of GitHub Issues and Excel, and unify the use of JIRA. By unifying to JIRA, each engineer can manage tasks more easily, and those who manage progress can also use JIRA's roadmaps for centralized management. JIRA roadmap example

For the third step, by passing environment parameter to deploy, the deployment status passed to environment will also be linked to JIRA. For reference, here is some of the deployment code by GitHub Actions we are using. In the environment parameter, $${ inputs.env }} is further passed, so that a key for each environment is created. Since $${ inputs.env } contains the environment name of the deployment destination, the deployment destination will be integrated with JIRA.

  DeployToECS:
    needs: [createTagName, ecr-image-check]
    if: ${{ needs.createTagName.outputs.TAG_NAME != '' && needs.ecr-image-check.outputs.output1 != '' }}
    runs-on: ubuntu-latest
    environment: ${{ inputs.env }}-factory-frontend
    steps:
      - Specific processing

As a result, the development status is managed by JIRA roadmaps and tickets, and each ticket can be viewed to manage whether it is under review, merged but not deployed, and to what environment it has been deployed. Status listed on each JIRA ticket

Visualizing the deployment status across all tickets, not just each ticket, is also possible. It is useful to see when each ticket was deployed and to which environment. Visualization of deployment status to each environment

Rely on automatic generation of release notes

For automatic generation of release notes, we decided to use GitHub's automatically generated release notes feature. The automatic generation of release notes is a feature that lists the titles and links of pull requests for the release note portion of GitHub's release feature. It can be better handled by setting a few rules. Here is an introduction.

Define the category of release content

The pull requests listed in the release notes are not categorized by default, making them difficult to view. Categorizing the pull requests helps keep release notes organized and easy to view. Categories are represented by labels. This time, I wanted to specifically display major changes and bug fixes as categories in the release notes, so I created 'enhancement' and 'bug' labels to represent each. You can also generate a list of pull request titles by category by creating a file .github/release.yml in the target repository and writing the following.

changelog:
  categories:
    - title: Major Changes
      labels:
        - 'enhancement'
    - title: Bug Fixes
      labels:
        - 'bug'
    - title: Others
      labels:
        - '*'

An image of the generated release notes is shown below. Pull requests labeled 'enhancement' and 'bug' are now classified as 'Major Changes' and 'Bug Fixes,' respectively All pull requests without 'enhancement' and 'bug' labels are classified as 'others.'

Category sorting and title correction at the time of pull request review

It is possible to generate release notes and then manually sort them, but once they are generated, it is difficult to remember and sort them. Therefore, at the time of the pull request review, we assign labels that correspond to the categories. We also check the titles to ensure they are appropriate for the content correction. To avoid forgetting to apply labels, others labels are given to refactoring, etc. This ensures that we know the review and category sorting are complete.

Results

Through the above efforts, we were able to successfully resolve the issues we were facing. In particular, the JIRA roadmaps have been referenced by other teams and are now used throughout the KINTO FACTORY project.

• Previously, GitHub Issues, JIRA, and Excel were used for task management, making progress difficult to manage. Now, centralized and managed in JIRA tickets and roadmaps.
• Previously, it was difficult to track which tasks are deployed in which environment. Now, deployment status of each environment is now visible in tickets.
• Previously, creating release notes when deploying to a test environment was troublesome. Now, work that used to take 2-3 minutes has drastically decreased to 10 seconds.

Future Development

By deploying to production environment, JIRA can measure two of the DevOps Four Keys in terms of speed. Our team will collaborate to identify the current status and target metrics for deployment frequency and change lead time for continuous improvement.

• Deployment frequency to production environment
• Lead time from merge to deploy to production environment

The KINTO FACTORY project is looking for team members who will work together to achieve service growth. If you are interested in this article or KINTO FACTORY, check out the job listings below!

• [KINTO FACTORY Full Stack Engineer] KINTO FACTORY Development Project Team, Tokyo
• [KINTO FACTORY Backend Engineer] KINTO FACTORY Development Project Team, Tokyo
• [KINTO FACTORY Frontend Engineer] KINTO FACTORY Development Project Team, Tokyo