All documentation

Argo CD Listener for Jira Coming soon

Setup & usage guide

Overview

Argo CD Listener publishes your Argo CD deployments to Jira. Each time Argo CD finishes syncing an application to a new revision, it sends an event to Argo CD Listener, which finds the Jira issues included in that deployment and adds the deployment to each of them, with its environment, version and status.

Argo CD Listener never connects to Argo CD. Argo CD pushes the events, so it can stay on a private network.

Argo CD sends each deployment to Argo CD Listener, which links it to Jira issues using your Git repositories

What you need

  • A Jira Cloud site where you are an administrator.
  • Argo CD with its notifications controller, able to make outbound HTTPS requests to api.magesoftware.com. The controller is part of the standard installation since Argo CD 2.3; an installation managed by the Argo CD Operator may need it turned on.
  • Permission to edit the argocd-notifications-cm ConfigMap.
  • An access token for GitHub, GitLab, Azure DevOps or AWS CodeCommit, unless your deployments carry Jira issue keys themselves (see step 2).

Installation

Argo CD Listener is available for Jira Cloud. Sign in to your Jira account, find Argo CD Listener among the Mage Software apps on the Atlassian Marketplace, and click Install.

After installation, open your organization's app management page, select your Atlassian site and open the Connected apps section. Find Argo CD Listener in the list, click the three-dot menu on the right and choose Configure. The first visit opens a setup wizard with four steps; you can leave it at any point and continue later.

Step 1: Argo CD instance

An Argo CD instance is the Argo CD installation whose deployments you want in Jira.

  • Instance name identifies the instance on every application and deployment, and in Jira. Pick something stable, such as the cluster, region or team.
  • Argo CD URL is optional and only used to build links from Jira back to Argo CD. An internal address works, as long as your users can open it. Without it, links use the address Argo CD reports for itself, and when it has none, they open the GitOps commit instead.

Send Argo CD events to Argo CD Listener

The wizard shows a webhook URL and an Argo CD notifications config generated for your site. Copy the config and merge it into the argocd-notifications-cm ConfigMap in the namespace where Argo CD runs:

kubectl -n argocd edit configmap argocd-notifications-cm

The config adds four keys under data:

data:
  # Where events are sent. The URL is generated for your site.
  service.webhook.jira-deployments: |
    url: https://api.magesoftware.com/argocd/webhooks/...
  # What is sent: the application, what it synced and its images.
  template.jira-deployed: |
    ...
  # When: once for each new revision an application has synced
  # successfully, as soon as the application is healthy.
  trigger.on-deployed: |
    ...
  # Which applications send it: all of them.
  subscriptions: |
    - recipients: [jira-deployments]
      triggers: [on-deployed]

Always copy the config from the wizard; the example above only shows its shape. If your ConfigMap already has a subscriptions key, add the new subscription to that list and keep the ones you have.

The webhook URL is the only credential Argo CD needs, and anyone who has it can report deployments for your site. Treat it like a secret.

When the config is first applied, Argo CD reports the current deployment of every healthy application. From then on it sends one event each time an application syncs a new revision. Re-syncing the same revision sends nothing.

Step 2: Jira issue linking

This step tells Argo CD Listener how to find the Jira issues included in a deployment. The choice applies to every application of the Argo CD instance. Choose the setup that matches how your deployment process identifies the code being deployed.

Deployment setupChoose it when
Jira issue keys in GitOps commitsThe commits that change your Argo CD applications, such as version bumps and promotions, carry Jira issue keys in their messages. Nothing else is needed.
Application version in GitOpsA version in the GitOps repository identifies a Git tag or commit in the application's repository.
Other deployment informationAn image tag, an Application annotation or a field your pipeline writes identifies the application code, or lists the Jira issue keys directly.

Where the version is read

For the last two setups, say where Argo CD Listener reads the value. Application version in GitOps offers the two Chart.yaml fields, the values file and a custom file. Other deployment information offers the image tag, an annotation and a custom file. Files are read from the GitOps repository at exactly the revision Argo CD synced.

SourceWhat is read
Chart.yaml › appVersionHelm's field for the version of the application being deployed.
Chart.yaml › versionThe chart's own version. Only useful when the chart is versioned together with the application.
values.yaml › image.tagThe image tag in the application's Helm values.
Custom file and keyAnother YAML file in the application's folder, such as an environment-specific values file. The key is a dotted path, for example app.commit or images[0].tag.
Container image tagThe tag of the image Argo CD deployed, for example ghcr.io/acme/payments:7f3a91c. Taken from the event; no repository is read.
Application annotationAn annotation your pipeline sets on the Argo CD Application, for example acme.io/jira-issues: PAY-123 PAY-127. Taken from the event.

What the value represents

  • A Git tag in the application's repository. If your tags differ from the value, set the Git tag format: use v{version} when the file says 2.4.0 and the tag is v2.4.0.
  • A commit SHA in the application's repository.
  • Jira issue keys, used directly without looking anything up. Offered only for Other deployment information.

For a tag or a commit, also choose which commits are inspected for Jira issue keys: all commits since the previous deployment of that application, which covers every change that shipped, or only the deployed commit. On AWS CodeCommit only the deployed commit can be inspected.

As a fallback, Argo CD Listener can use the message of the GitOps commit when no Jira issue keys are found elsewhere. The panel at the bottom of the step reads your choices back as the steps Argo CD Listener will take for each deployment.

Jira issue keys look like PAY-123. Include them in commit messages so the issues can be found.

Step 3: Repositories

Argo CD Listener reads two kinds of repositories. Which of them are needed depends on the Jira issue linking you chose, and the wizard marks each as required, recommended, optional or not needed.

  • GitOps repositories contain your Argo CD Application manifests and deployment configuration. They tell Argo CD what to deploy and where. Argo CD Listener reads the version from them and imports your applications from their manifests.
  • Application repositories contain the source code of the services you deploy. Argo CD Listener uses them to identify the code changes and Jira issues included in each deployment.

Connections

A connection holds the credentials for one Git host or organization. Create one per organization and reuse it for both kinds of repositories when they live in the same place. Argo CD Listener only reads from your repositories. Each provider asks for:

ProviderCredentials
GitHubA personal access token with the repo, read:org, read:user and read:project scopes.
GitLabA personal access token with the read_api, read_user and read_repository scopes. Self-managed GitLab is supported.
Azure DevOpsA personal access token with Code (read) permission, scoped to the organization you name. Azure DevOps Server is supported.
AWS CodeCommitThe access key of an IAM user with the AWSCodeCommitReadOnly policy.

GitOps repository settings

  • Application manifests folders: the folders that contain your Argo CD Application manifests, as comma-separated paths from the repository root, for example argocd/, clusters/prod/apps. Use / for the whole repository.
  • Environment type: the Jira environment type its applications get: production, staging, testing or development. Give every application the same type, or derive it from environment rules when one repository holds several environments.

An environment rule is a list of patterns with * as the wildcard, matched against the application's name, path, destination namespace and manifest path. The first matching rule wins. The default rules recognise the usual words, so payments-prod, apps/staging/payments and the namespace dev are mapped without any change. An application that no rule matches is shown as unmapped.

Application repository settings

Choose whether Argo CD Listener may read everything the connection can access or only the repositories you select. Each application is later matched to one of them.

Step 4: Applications

Argo CD Listener scans the manifests folders and lists the Argo CD applications it found, each with its environment type and, when the linking needs one, the application repository suggested for it by name: payments-production is matched to acme/payments-service. Correct any match that is wrong, tick the applications whose deployments should be published to Jira, and finish setup.

  • Applications you create in Argo CD later are added automatically when they first deploy.
  • Applications generated by an ApplicationSet have no manifest to scan, so they are also added when they first deploy.
  • Without a GitOps repository there is nothing to scan, and every application is added when it first deploys.

Deployments in Jira

Once setup is finished, every deployment that includes a Jira issue appears in the Deployments section of that issue's development panel, with the environment, the version, the status and a link back to the application in Argo CD. Jira's Deployments feature is turned on for each project in its settings; a project that has it also shows the deployments on its Deployments timeline.

Argo CD deployments to production, staging and development shown on a Jira issue

The same version deployed to another environment is a separate deployment, so an issue shows each environment it has reached.

After setup

The configuration page now shows five tabs.

  • Applications: the Argo CD applications Argo CD Listener knows, with their environment type, source repository and a Publishing switch. Add applications from new manifests, change an application's repository, or update the mappings of many applications at once.
  • Argo CD instances: the instance name and URL, the webhook URL and notifications config, and the Jira issue linking.
  • Git connections: the GitOps and application repositories, their settings, and the credentials of each connection. Re-scan a GitOps repository to learn about applications that are not added yet.
  • Deployments: every deployment Argo CD reported in the last 30 days and what became of it. See Troubleshooting for the results.
  • Settings: pause publishing to Jira for the whole site. Resuming brings back what was publishing before.
The Deployments tab, listing recent deployments with their application, environment, version, Jira issue keys and result

Limits to know

  • Setup creates one Argo CD instance for a Jira site, with one webhook URL, one instance name and one Jira issue linking. A second instance cannot be added yet.
  • A deployment is reported when Argo CD syncs a new revision. A change that creates no new commit, such as an image updater that does not write back to Git or a mutable tag like latest, is not reported.
  • The Jira issue linking and the Git tag format apply to every application of the instance.
  • Each application has one application repository.
  • With the container image tag as the source, one image is read, so all images of an application should share the tag.
  • Jira issue keys are read from commit messages, not from pull request titles.
  • On AWS CodeCommit only the deployed commit is inspected for Jira issue keys. Squash-merging each change into one commit avoids missing issues.
  • An app-of-apps parent is listed like any other application. Leave its publishing off: its children report their own deployments.
  • A repository can be connected to one Mage Software app installation at a time. Connecting a repository that Git Listener already uses moves it to Argo CD Listener.
  • Up to 1,000 applications are supported per Jira site.

Troubleshooting

No deployments appear on the Deployments tab

  • Check that all four keys of the notifications config are in argocd-notifications-cm, and that an existing subscriptions list was extended, not replaced.
  • Check that the notifications controller can reach api.magesoftware.com over HTTPS.
  • An event is sent only after a sync has succeeded and the application is healthy, and only once for each revision.
  • Read the controller's log for the on-deployed trigger and the jira-deployments webhook:
kubectl -n argocd logs deployment/argocd-notifications-controller

A deployment is listed but is not in Jira

The Result column of the Deployments tab says what became of each deployment, with a reason when it did not reach Jira.

ResultWhat it means
LinkedThe deployment is in Jira, on the issues listed beside it.
WaitingThe Jira issues of the deployment are known and it has not been sent to Jira yet. A waiting deployment is tried again.
No issue keysNo Jira issue key has been found for the deployment. The reason says what is missing, for example that the Git tag was not found in the application's repository or that no Chart.yaml with an appVersion was found. Without a reason, check that your commit messages contain Jira issue keys.
FailedJira did not accept the deployment. It is not sent again; the reason shows Jira's answer.
PausedPublishing is off for the application, or paused for the whole site on the Settings tab.

An application's environment is "unmapped"

No environment rule matched its name, path or namespace, so its deployments are published without an environment type. Set the type with Update application mappings on the Applications tab. To have applications like it mapped when they are added, edit the environment rules of the GitOps repository on the Git connections tab.

Links in Jira open a commit, not Argo CD

The instance has no Argo CD URL, and Argo CD reported no address of its own. Add the URL on the Argo CD instances tab; deployments reported from then on link to the application in Argo CD.

Further information

Have a question about your Argo CD setup or need a hand? Reach out via our feedback form and we'll be happy to help.