{"id":44988256,"url":"https://github.com/kosli-dev/jira-integration-example","last_synced_at":"2026-02-18T20:28:27.327Z","repository":{"id":278701361,"uuid":"936488031","full_name":"kosli-dev/jira-integration-example","owner":"kosli-dev","description":"An example on how kosli can integrate with jira","archived":false,"fork":false,"pushed_at":"2025-09-17T09:55:11.000Z","size":266,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-17T11:41:48.586Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/kosli-dev.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-21T07:07:30.000Z","updated_at":"2025-09-17T09:55:12.000Z","dependencies_parsed_at":"2025-04-03T06:23:47.971Z","dependency_job_id":"17262caa-630e-43f3-be4f-bcfac7879aa1","html_url":"https://github.com/kosli-dev/jira-integration-example","commit_stats":null,"previous_names":["kosli-dev/jira-integration-example"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/kosli-dev/jira-integration-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosli-dev%2Fjira-integration-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosli-dev%2Fjira-integration-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosli-dev%2Fjira-integration-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosli-dev%2Fjira-integration-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kosli-dev","download_url":"https://codeload.github.com/kosli-dev/jira-integration-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kosli-dev%2Fjira-integration-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29594256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T18:54:29.675Z","status":"ssl_error","status_checked_at":"2026-02-18T18:50:50.517Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-02-18T20:28:24.362Z","updated_at":"2026-02-18T20:28:27.318Z","avatar_url":"https://github.com/kosli-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jira-integration-example\nAn example on how Kosli can integrate with Jira and GitHub in a\ncomplete release process.\n\n\n# Simulated project\n\nThe project has two applications `frontend` and `backend`. The\ntwo applications are in the same git repository, but are \nupdated and released independently.\n\nThe \"source code\" for the two applications are the two files\n```\napps/backend/backend-content.txt\napps/frontend/frontend-content.txt\n```\nTo simulate a change of the software in an application just\nincrease the `counter=xx` number in the file.\n\nThere is a CI-pipeline build step for the \n[backend](https://github.com/kosli-dev/jira-integration-example/actions/workflows/build-backend.yml)\nand one for the\n[frontend](https://github.com/kosli-dev/jira-integration-example/actions/workflows/build-frontend.yml).\nThe CI-pipeline are only triggerd on changes to that particular application.\n\nThere are no real servers in this demo. We use some git tags to indicate what software is\nrunning on which server:\n- running-staging-backend\n- running-staging-frontend\n- running-prod-backend\n- running-prod-frontend\n\nFor development we use the latest version checked in on `main`\n\nThere are three GitHub actions that simulate the reporting of snapshots. \n- Report development snapshot\n- Report staging snapshot\n- Report prod snapshot\nThey trigger automatically once an hour, but can also be triggered manually.\n\nThere is a \n[kosli-setup](https://github.com/kosli-dev/jira-integration-example/actions/workflows/setup-kosli.yml)\nCI-pipeline to create all flows, environments, custom attestation types and policies.\n\n\n# Software Process\n\nThe software process works like this:\n- All commits to `main` must have to have a `pull-request` and a `jira-issue` reference.\n- Applications in repo are released independently.\n- Any developer can promote the current dev-server software to the staging-server.\n- A developer decides when he/she thinks the current staging-server software is ready\nfor release and creates a **release candidate**\n- The **release candidate** shall be visible in Jira with a list of Jira-issues that are\nincluded in the release.\n- The product owner shall review the **release candidate** in Jira and test it on staging-server.\n- Any issues found in a **release candidate** must be mitigated before deployment to production-server.\n- The product owner is free to make new Jira-issues or just talk with developers.\n- Developer fixes the issue, deploy the fix to staging and then updates the **release candidate**\nwith any ny Jira-issues.\n- When satisfied with the **release candidate** the product owner approves it in Jira.\n- When a **release candidate** is approved by all approvers it will automatically be\ndeployed to production-server.\n- There can only be one open **release candidate** at a time.\n\n\n# Reporting to Kosli\n\nThe software delivery process is documented in Kosli. \n\nFor the source control and build of software we use the following flows:\n- `jira-example-source` - document that all pushes to main has pull-request and Jira-issue reference\n- `jira-example-frontend` - document the build of frontend artifact and also the pull-request and Jira-issue reference\n- `jira-example-backend` - document the build of backend artifact and also the pull-request and Jira-issue reference\nAll flows uses the git-commit as the trail name.\n\nFor the servers we use the following **server** environments:\n- `jira-integration-example-dev` - document what is running on development server\n- `jira-integration-example-staging` - document what is running on staging server\n- `jira-integration-example-prod` - document what is running on production server\n\n\n# Release process\n\nMerges to `main` that updates any of the applications trigger a build and automatic deployment\nto dev-server of that applications.\n\n## Promote to staging\nThe developers are free to decide when they want to promote what is running on dev-server to staging-server.\nThe developers can trigger the **Deploy to Staging** GitHub action by running\n```\nmake deploy_to_staging\n```\nThis job does the following:\n- Use Kosli to find out what software that is currently running on development. \nThis includes the fingerprint of the artifact and the commit it was built from. \nIn this simulated setup we use the commit to find the correct version  to deploy \nto staging for each artifact.\n- In a normal setup the applications that had to be updated would be deployed, \nbut in this simulated setup we only update some git tags.\n\n## Release to production\nWhen a developer thinks that what is currently running in staging should be released\nto production they  create a **release candidate**. The developers can trigger the\n**Generate Jira release** GitHub action by running:\n```\nmake generate_jira_release\n```\nThis job does the following:\n- Use Kosli to find out what software that is currently running on staging and\nproduction.\n- Use Kosli to find all Jira-issues that has been referenced in git commits\nsince last deployment to production\n- Creat a Jira-release. Use date-time as name of release for now.\n- Add all Jira-issues to the Jira-release\n\nThe Jira API does not support adding an approver to a release, so the product owner\nhas to manually add them self as an approver in the UX. It is possible to add\nmultiple approvers.\n\nIf the product owner finds a problem with the release they inform the\ndevelopers.\n\nAfter the developers has added a fix and deployed it to staging they update the\n**release candidate**. The developers can trigger the\n**Generate Jira release** GitHub action by running:\n```\nmake generate_jira_release\n```\n\nWhen all approvers have set the approval to `APPROVED` the software can be deployed\nto production.\n\nThere is a **Release to Prod** GitHub action that runs every hour. It can also be\ntriggered manually by running:\n```\nmake check_release_to_prod\n```\nThis job does the following:\n- Gets the current release candidate from Jira\n- Check that there is at least one approver\n- Checks that all approvers has set the state to `APPROVED`\n- Attest to Kosli that the release candidate was approved\n- Deploy software to prod-server. In this simulated environment we just move\nthe 'running-prod-xxx' tags.\n- Set the Jira release to **Released**\n\n\n# Demo of complete process\nIt is possible to run a demo of the complete process.\nGo to the [jira board](https://kosli-team.atlassian.net/jira/software/projects/OPS/boards/1)\nand add two new Jira-issues. The Jira-issues have issue-key like OPS-11 and OPS-12\nGo to the [release page](https://kosli-team.atlassian.net/projects/OPS?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page)\nand make sure there are no **Unreleased** versions. If there is you have to archive them.\n\nRun the following script with the two IDs you created (currently only tested on Linux)\n```\n./scripts/demo-jira-release.sh OPS-11 OPS-12\n```\nThe script takes approximately 10 minutes to run, and requires some interaction\nafter approximately 8 minutes.\n\nYou should be able to see the flows and environments in Kosli and also see that\nthe release is updated in Jira.\n\nWe currently also have a `jira-example-release` flow, but this needs some improvement.\n\nhttps://app.kosli.com/kosli-public/flows/\nhttps://app.kosli.com/kosli-public/environments/\n\n\n# Custom attestation of approval\nThe approval done in Jira contains a list of the approvers. To properly store and\nevaluate this data we use a custom attestation type `custom:approval-jira`.\nHow this custom attestation type is created is documented in the `setup-kosli.yml`,\nand usage of it in `release-to-prod.yml`.\n\n\n# Things to improve\n\nMake the scripts a little more streamlined and make it easy to just give\na list of apps/environments and loop over them.\n\nI report the Jira issue and pull request on both the source and build flows. A link\nfrom the source trail to build trail would be nice. But for proper linking we\nneed to let a trail event on one trail trigger also a trail event on the other trails that it\nlinks to.\n\nA release is very important for the customer I think we should have that\nconsept in Kosli. What do we need?\n- In this case we only want things in prod that has been released. Provenance \nfrom a build to staging is not compliant.\n- A release consists of a set of versions of applications. We should record\nthat combination.\n- Do we want to validate that the combination of software in a release is\nalso the combination running in production?\n- Record who approved a release\n- Record the list of Jira issues included in release (also state if they want)\n- I do a lot of API calls to get the list of commits in a release, and then\nI loop over all the commits to collect all the Jira issues included. This\ngives me some complicated bash scripts, which is hard to maintain.\n\n\n# Customer demo\n\n## Preparation\nMake sure there are no pending release in\nhttps://kosli-team.atlassian.net/projects/OPS?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page\n\nMake sure the environment reporting is up to date\nmake report_all_envs\n\n## With customer\nShow them the board https://kosli-team.atlassian.net/jira/software/projects/OPS/boards/1\n\nAdd a jira issue in **IN PROGRESS** with some description: Make the app great again\n\nShow them that there are no open releases\n  https://kosli-team.atlassian.net/projects/OPS?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page\n\nMake a branch that matches the name\n  git checkout -b OPS-xx-improve-app\n\nUpdate the two files by increasing the number:\n  apps/backend/backend-content.txt\n  apps/frontend/frontend-content.txt\n\nCommit, push and make a PR\n  git commit -m \"Made the app create agin\"\n  git push\n  gh pr create\n\nApprove the PR in github https://github.com/kosli-dev/jira-integration-example/pulls\n\nYou should now have three jobs running in actions\n  - Build Backend\n  - Build Frontend\n  - Attest Source Controls\n\nLet all jobs finish and then force reporting of what is running in each environment\n  make report_all_envs\n\nYou can now show that the updated is running in development\n  https://app.kosli.com/kosli-public/environments/jira-integration-example-dev/snapshots/\n\nDeploy development SW to staging and when that job has finished you can report environments again\n  make deploy_to_staging\n  WAIT\n  make report_all_envs\n\nThe SW is now running in staging\n  https://app.kosli.com/kosli-public/environments/jira-integration-example-staging/snapshots/\n\nCreate a release candidate\n  make generate_jira_release\n\nShow the customer the new release\n  https://kosli-team.atlassian.net/projects/OPS?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page\n\nPress the release and show them that the Jira issue you created is part of the release. If there are more there\nit is just because there was some other updates also included.\n\nThere is no API in Jira to add an approver for a release so you have to do this manually. You find this on the\nright hand side. You can also show them that it is marked as **Unreleased**\n\nYou can now trigger a release to production which will fail since not all approvers has approved it\n  make check_release_to_prod\n\n### Fast demo\nDepending on how much time you have now you can release what you have now by setting the release to APPROVED\nin the release web page. Then run the release, wait and then update the environments\n  make check_release_to_prod\n  WAIT\n  make report_all_envs\n\n### Extended demo\nGo back to the Jira board and make a new Jira issue: Improve frontend\n- make branch\n- update apps/frontend/frontend-content.txt\n- git commit, push, create pr\n- approve pr\n- WAIT\n- make report_all_envs\n- WAIT\n- make deploy_to_staging\n- WAIT\n- make report_all_envs\n- WAIT\n\nNow we have the new fix for frontend running in staging. The backend SW is the same as before.\n\nUpdate the Jira release so we also include the new Jira issue\n  make generate_jira_release\n\nShow the release (you must reload the page) to show that the new Jira issue is in the list\n\nNow you can now follow the steps in Fast Demo to finish the demo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkosli-dev%2Fjira-integration-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkosli-dev%2Fjira-integration-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkosli-dev%2Fjira-integration-example/lists"}