-
Notifications
You must be signed in to change notification settings - Fork 62
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
replace integration readmes with links to docs (#195)
* replace integration readmes with links to docs * replace integration readmes with links to docs * replace integration readmes with links to docs * replace integration readmes with links to docs * replace integration readmes with links to docs * replace integration readmes with links to docs * replace integration readmes with links to docs --------- Co-authored-by: Hadar <[email protected]>
- Loading branch information
hadar-co
and
Hadar
authored
Oct 30, 2023
1 parent
e43c328
commit 7a39f40
Showing
14 changed files
with
45 additions
and
5,254 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,259 +1,7 @@ | ||
| # Jira | ||
|
|
||
| Integration to import information from Jira into Port. | ||
| An integration used to import Jira resources into Port. | ||
|
|
||
| The integration supports importing issues and projects from your Jira cloud account to Port, according to your mapping and definition. | ||
| #### Install & use the integration - [Integration documentation](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/project-management/jira) | ||
|
|
||
| **Note:** the integration supports Jira Cloud at the moment, support for Jira Server is being worked on. | ||
|
|
||
| ## Development Requirements | ||
|
|
||
| - Python3.11.0 | ||
| - Poetry (Python Package Manager) | ||
| - Port-Ocean | ||
|
|
||
| ## Deployment to Port | ||
|
|
||
| For more information about the installation visit the [Port Ocean helm chart](https://github.com/port-labs/helm-charts/tree/main/charts/port-ocean) | ||
|
|
||
| ```bash | ||
| # The following script will install an Ocean integration in your K8s cluster using helm | ||
| # integration.identifier: Change the identifier to describe your integration | ||
| # integration.config.appHost: The host of the Port Ocean app. Used to set up the integration endpoint as the target for Webhooks created in Jira | ||
| # integration.config.jiraHost: The URL of your Jira, for example: https://example.atlassian.net | ||
| # integration.secrets.atlassianUserEmail: The email of the user used to query Jira | ||
| # integration.secrets.atlassianUserToken: Jira API token generated by the user specified under atlassianUserEmail | ||
| # ingress.annotations."nginx\.ingress\.kubernetes\.io/rewrite-target": Change the annotation value and key to match your ingress controller | ||
|
|
||
| helm upgrade --install my-jira-integration port-labs/port-ocean \ | ||
| --set port.clientId="CLIENT_ID" \ | ||
| --set port.clientSecret="CLIENT_SECRET" \ | ||
| --set initializePortResources=true \ | ||
| --set integration.identifier="my-jira-integration" \ | ||
| --set integration.type="jira" \ | ||
| --set integration.eventListener.type="POLLING" \ | ||
| --set integration.config.appHost="https://example.com" \ | ||
| --set integration.config.jiraHost="https://example.atlassian.net" \ | ||
| --set integration.secrets.atlassianUserEmail="[email protected]" \ | ||
| --set integration.secrets.atlassianUserToken="<JIRA_API_TOKEN>" \ | ||
| --set ingress.enabled=true \ | ||
| --set ingress.annotations."nginx\.ingress\.kubernetes\.io/rewrite-target"= / | ||
| ``` | ||
|
|
||
| ## Supported Kinds | ||
|
|
||
| ### Project | ||
|
|
||
| The mapping should refer to one of the projects from the example response: [Jira documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get) | ||
|
|
||
| <details> | ||
| <summary>blueprints.json</summary> | ||
|
|
||
| ```json | ||
| { | ||
| "identifier": "project", | ||
| "title": "Jira Project", | ||
| "icon": "Jira", | ||
| "description": "A Jira project", | ||
| "schema": { | ||
| "properties": { | ||
| "url": { | ||
| "title": "Project URL", | ||
| "type": "string", | ||
| "format": "url", | ||
| "description": "URL to the project in Jira" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| </details> | ||
| <details> | ||
| <summary>port-app-config.yaml</summary> | ||
|
|
||
| ```yaml | ||
| createMissingRelatedEntities: true | ||
| deleteDependentEntities: true | ||
| resources: | ||
| - kind: project | ||
| selector: | ||
| query: "true" | ||
| port: | ||
| entity: | ||
| mappings: | ||
| identifier: .key | ||
| title: .name | ||
| blueprint: '"project"' | ||
| properties: | ||
| url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key | ||
| ``` | ||
| </details> | ||
| ### Issue | ||
| The mapping should refer to one of the issues in the example response: [Jira documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-get) | ||
| <details> | ||
| <summary>blueprints.json</summary> | ||
| ```json | ||
| { | ||
| "identifier": "issue", | ||
| "title": "Jira Issue", | ||
| "icon": "Jira", | ||
| "schema": { | ||
| "properties": { | ||
| "url": { | ||
| "title": "Issue URL", | ||
| "type": "string", | ||
| "format": "url", | ||
| "description": "URL to the issue in Jira" | ||
| }, | ||
| "status": { | ||
| "title": "Status", | ||
| "type": "string", | ||
| "description": "The status of the issue" | ||
| }, | ||
| "issueType": { | ||
| "title": "Type", | ||
| "type": "string", | ||
| "description": "The type of the issue" | ||
| }, | ||
| "components": { | ||
| "title": "Components", | ||
| "type": "array", | ||
| "description": "The components related to this issue" | ||
| }, | ||
| "assignee": { | ||
| "title": "Assignee", | ||
| "type": "string", | ||
| "format": "user", | ||
| "description": "The user assigned to the issue" | ||
| }, | ||
| "reporter": { | ||
| "title": "Reporter", | ||
| "type": "string", | ||
| "description": "The user that reported to the issue", | ||
| "format": "user" | ||
| }, | ||
| "creator": { | ||
| "title": "Creator", | ||
| "type": "string", | ||
| "description": "The user that created to the issue", | ||
| "format": "user" | ||
| } | ||
| } | ||
| }, | ||
| "relations": { | ||
| "project": { | ||
| "target": "project", | ||
| "title": "Project", | ||
| "description": "The Jira project that contains this issue", | ||
| "required": false, | ||
| "many": false | ||
| }, | ||
| "parentIssue": { | ||
| "target": "issue", | ||
| "title": "Parent Issue", | ||
| "required": false, | ||
| "many": false | ||
| }, | ||
| "subtasks": { | ||
| "target": "issue", | ||
| "title": "Subtasks", | ||
| "required": false, | ||
| "many": true | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| </details> | ||
| <details> | ||
| <summary>port-app-config.yaml</summary> | ||
|
|
||
| ```yaml | ||
| createMissingRelatedEntities: true | ||
| deleteDependentEntities: true | ||
| resources: | ||
| - kind: issue | ||
| selector: | ||
| query: "true" | ||
| port: | ||
| entity: | ||
| mappings: | ||
| identifier: .key | ||
| title: .fields.summary | ||
| blueprint: '"issue"' | ||
| properties: | ||
| url: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key | ||
| status: .fields.status.name | ||
| issueType: .fields.issuetype.name | ||
| components: .fields.components | ||
| assignee: .fields.assignee.displayName | ||
| reporter: .fields.reporter.displayName | ||
| creator: .fields.creator.displayName | ||
| relations: | ||
| project: .fields.project.key | ||
| parentIssue: .fields.parent.key | ||
| subtasks: .fields.subtasks | map(.key) | ||
| ``` | ||
| You can add a [JQL](https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/) query to the Jira issues ingest process, add a `jql` key to the `selector` section to perform the filtering. | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| resources: | ||
| - kind: issue | ||
| selector: | ||
| query: "true" | ||
| jql: "issueKey=EXAMPLE-1234" | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ## Development | ||
|
|
||
| ### Installation | ||
|
|
||
| ```sh | ||
| make install | ||
| ``` | ||
|
|
||
| ### Runnning Localhost | ||
|
|
||
| ```sh | ||
| make run | ||
| ``` | ||
|
|
||
| or | ||
|
|
||
| ```sh | ||
| ocean sail | ||
| ``` | ||
|
|
||
| ### Running Tests | ||
|
|
||
| `make test` | ||
|
|
||
| ### Access Swagger Documentation | ||
|
|
||
| > <http://localhost:8080/docs> | ||
|
|
||
| ### Access Redoc Documentation | ||
|
|
||
| > <http://localhost:8080/redoc> | ||
|
|
||
| ### Folder Structure | ||
|
|
||
| The Jira integration suggested folder structure is as follows: | ||
|
|
||
| ``` | ||
| Jira/ | ||
| ├─ main.py | ||
| ├─ pyproject.toml | ||
| └─ Dockerfile | ||
| ``` | ||
| #### Develop & improve the integration - [Ocean integration development documentation](https://ocean.getport.io/develop-an-integration/) |
Oops, something went wrong.