GitHub Actions for syncing the project with the Espressif Jira system
APACHE-2.0 License
Once a JIRA issue is created and synced from GitHub, a Remote Issue Link is automatically generated for the JIRA issue. This link includes a "globalID" that corresponds to the URL of the GitHub issue. This mechanism ensures that any future changes to the GitHub issue are tracked and reflected in the JIRA issue, maintaining a consistent link between the two platforms.
This design ensures that the integration between GitHub and JIRA remains dynamic and adaptable to changes, providing a robust solution for tracking issues across both platforms.
Creating a Remote Issue Link with the appropriate globalID
directly through the JIRA Web UI is not feasible without leveraging the JIRA API. However, you can manually establish a connection between an existing GitHub issue and a JIRA issue by following these steps:
issue in issuesWithRemoteLinksByGlobalId("GitHub Issue URL")
to check for existing links.GitHub Issue title (JIRAKEY-123)
. This modification helps in identifying the linked issues easily.Upon the next update to the GitHub issue (which might occur immediately if you follow the steps sequentially), the GitHub action will automatically generate the "Synced from" link, establishing a manual link between the issues.
If the GitHub issue URL is not present in the JIRA issue description, the GitHub action will not create a link. This safeguard is designed to prevent unauthorized or unintended updates to JIRA issues from external sources.
The GitHub to JIRA Issue Sync Action intelligently creates JIRA issues with specific types based on the labels attached to the GitHub issue. This feature ensures that the issue types in JIRA accurately reflect the nature or category of the issue as determined in GitHub.
Type: <issue type>
. The search for matching labels is case insensitive, ensuring flexibility in label naming conventions.JIRA_ISSUE_TYPE
environment variable to determine the issue type for the new JIRA issue. If this environment variable is not defined, the default issue type used is "Task".There are certain limitations to the data and events that can be synchronized:
# FILE: .github/workflows/sync-jira.yml
---
# This GitHub Actions workflow synchronizes GitHub issues, comments, and pull requests with Jira.
# It triggers on new issues, issue comments, and on a scheduled basis.
# The workflow uses a custom action to perform the synchronization with Jira (espressif/sync-jira-actions).
name: 🔷 Sync to Jira
run-name: >
Sync to Jira -
${{ github.event_name == 'issue_comment' && 'Issue Comment' ||
github.event_name == 'schedule' && 'New Pull Requests' ||
github.event_name == 'issues' && 'New Issue' ||
github.event_name == 'workflow_dispatch' && 'Manual Sync' }}
on:
issues: {types: [opened]}
issue_comment: {types: [created, edited, deleted]}
schedule: [cron: '0 * * * *']
workflow_dispatch:
inputs:
action: {description: 'Action to be performed', required: true, default: 'mirror-issues'}
issue-numbers: {description: 'Issue numbers to sync (comma-separated)', required: true}
jobs:
sync-to-jira:
name: >
Sync to Jira -
${{ github.event_name == 'issue_comment' && 'Issue Comment' ||
github.event_name == 'schedule' && 'New Pull Requests' ||
github.event_name == 'issues' && 'New Issue' ||
github.event_name == 'workflow_dispatch' && 'Manual Sync' }}
runs-on: ubuntu-latest
permissions:
contents: read
issues: write
pull-requests: write
steps:
- name: Check out
uses: actions/checkout@v4
- name: Run synchronization to Jira
uses: espressif/sync-jira-actions@v1
with:
cron_job: ${{ github.event_name == 'schedule' && 'true' || '' }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
JIRA_PASS: ${{ secrets.JIRA_PASS }}
JIRA_PROJECT: IDFSYNTEST # <---- update for your Jira project
JIRA_COMPONENT: GitHub
JIRA_URL: ${{ secrets.JIRA_URL }}
JIRA_USER: ${{ secrets.JIRA_USER }}
[!TIP] In this repository, there is a file named sync-jira.yml. You can download it and place it in your project at
.github/workflows/sync-jira.yml
.
For cases where you need to manually sync issues and pull requests that were not automatically captured by the Sync Jira workflow, this GitHub Action provides a solution. It allows for the manual synchronization of both new and old issues and pull requests directly to your JIRA project.
This action introduces two parameters for manual triggering:
action
: Specifies the action to be performed, with a default value of mirror-issues
.issue-numbers
: Lists the numbers of the issues and pull requests that you wish to sync to JIRA.This workflow can be triggered manually from the Actions tab in your repository, allowing you to specify the issues or pull requests to be synced by entering their numbers.
This ensures that even items not caught by the automatic sync process can still be integrated into your JIRA project for tracking and management.
[!NOTE] For Espressif projects (https://github.com/espressif/), you don't need to set any environment variables. This action workflow will work out of the box, as the variables important for authentication with Jira are inherited from the organization level.
The GitHub to JIRA Issue Sync workflow requires the configuration of specific environment variables and secrets to operate effectively. These settings ensure the correct creation and updating of issues within your JIRA project based on activities in your GitHub repository.
Below is a detailed table outlining the necessary configurations:
Variable/Secret | Description | Requirement |
---|---|---|
JIRA_PROJECT |
Specifies the Jira project to synchronize with. | Mandatory |
JIRA_ISSUE_TYPE |
Specifies the JIRA issue type for new issues. Defaults to "Task" if not set. | Optional |
JIRA_COMPONENT |
The name of a JIRA component to add to every synced issue. The component must exist in JIRA. | Optional |
JIRA_URL |
The main URL of your JIRA instance. | Inherited |
JIRA_USER |
The username used for logging into JIRA (basic auth). | Inherited |
JIRA_PASS |
The JIRA token (for token auth) or password (for basic auth) used for logging in. | Inherited |
JIRA_URL
, JIRA_USER
, JIRA_PASS
- These secrets are inherited from the GitHub organizational secrets, as they are common to all projects within the organization.[!WARNING] Do not to set secrets at the individual repository level to avoid conflicts and ensure a unified configuration across all projects.
JIRA_PASS
, prefix the token value with token:
(e.g., token:Xyz123**************ABC
). This prefix helps distinguish between password and token types, and it will be removed by the script before making the API call.If you encounter any issues, feel free to report them in this project's issues or create Pull Request with your suggestion.
📘 If you are interested in contributing to this project, see the project Contributing Guide.