diff --git a/docs/site/docs/data-security.md b/docs/site/docs/data-security.md index f2df10dd6..7c112a511 100644 --- a/docs/site/docs/data-security.md +++ b/docs/site/docs/data-security.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # Data handling & security diff --git a/docs/site/docs/examples/_category_.json b/docs/site/docs/examples/_category_.json index 54600239d..572fa6222 100644 --- a/docs/site/docs/examples/_category_.json +++ b/docs/site/docs/examples/_category_.json @@ -1,4 +1,4 @@ { "label": "Enterprise-Ready Plugins", - "position": 6 + "position": 5 } diff --git a/docs/site/docs/examples/dev-daily.md b/docs/site/docs/examples/dev-daily.md index feb25bc83..fad09e3e5 100644 --- a/docs/site/docs/examples/dev-daily.md +++ b/docs/site/docs/examples/dev-daily.md @@ -4,6 +4,9 @@ description: A dashboard that consolidates developers' daily activities like pul sidebar_position: 2 --- +import JiraIntegration from "../integrations/jira.mdx"; +import GithubIntegration from "../integrations/github.mdx"; + # Dev Daily Plugin The Dev Daily Plugin provides developers with a consolidated dashboard of their daily development activities, including pull requests, tasks, and reviews. This plugin helps developers efficiently plan and manage their day by bringing together key information in one place. @@ -13,9 +16,205 @@ The Dev Daily Plugin provides developers with a consolidated dashboard of their ## Prerequisites - Complete the [Getting Started](/getting-started) guide -- Jira and Github accounts +- Jira and Github accounts with the necessary permissions + - For Jira obtain a [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) + +## Setup integrations + +In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab. + +![Port Settings](/img/settings-page.png) + +Yours will be empty, so you'll need to add your Jira and Github integrations. + +Click on the **Add Integration** button, and follow the instructions to add both Jira and Github integrations. + + + + + +## Setup the mappings & blueprints + +In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab. + +### Add the blueprints - Pull Request & Task + +Click on **Add Blueprint** and add the following two blueprints: + +
+Pull Request Blueprint + +```json +{ + "identifier": "dev-daily-pull-request", + "title": "Pull Request", + "icon": "Github", + "schema": { + "properties": { + "creator": { + "title": "Creator", + "type": "string" + }, + "assignees": { + "title": "Assignees", + "type": "array" + }, + "reviewers": { + "title": "Reviewers", + "type": "array" + }, + "status": { + "title": "Status", + "type": "string", + "enum": ["merged", "open", "closed"], + "enumColors": { + "merged": "purple", + "open": "green", + "closed": "red" + } + }, + "closedAt": { + "title": "Closed At", + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "title": "Updated At", + "type": "string", + "format": "date-time" + }, + "mergedAt": { + "title": "Merged At", + "type": "string", + "format": "date-time" + }, + "link": { + "format": "url", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} +} +``` + +
+ +
+Task Blueprint + +```json +{ + "identifier": "dev-daily-task", + "title": "Task", + "icon": "Jira", + "schema": { + "properties": { + "assignee": { + "type": "string", + "title": "Assignee" + }, + "status": { + "icon": "DefaultProperty", + "title": "Status", + "type": "string", + "enum": ["To Do", "In Progress", "Done"], + "enumColors": { + "To Do": "turquoise", + "In Progress": "yellow", + "Done": "green" + } + }, + "link": { + "type": "string", + "title": "Link", + "format": "url" + } + }, + "required": ["assignee", "status", "link"] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} +} +``` + +
+ +### Add the mappings + +Click on the `MAPPING` button near the **GitHub** integration. and paste the following YAML: + +
+Pull Request Mapping + +```yaml +resources: + - kind: pull-request + selector: + query: "true" + port: + entity: + mappings: + identifier: .head.repo.name + (.id|tostring) + title: .title + blueprint: '"dev-daily-pull-request"' + properties: + creator: .user.login + assignees: "[.assignees[].login]" + reviewers: "[.requested_reviewers[].login]" + status: .status + closedAt: .closed_at + updatedAt: .updated_at + mergedAt: .merged_at + prNumber: .id + link: .html_url +``` + +
+ +Now click on the `MAPPING` button near the **Jira** integration. and paste the following YAML: + +
+Task Mapping + +```yaml +deleteDependentEntities: true +createMissingRelatedEntities: true +enableMergeEntity: true +resources: + - kind: issue + selector: + query: "true" + jql: (created >= -1w) OR (updated >= -1w) + port: + entity: + mappings: + identifier: .key + title: .fields.summary + blueprint: '"dev-daily-task"' + properties: + link: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key + status: .fields.status.statusCategory.name + creator: .fields.creator.emailAddress + created: .fields.created + updated: .fields.updated + resolutionDate: .fields.resolutiondate + assignee: .fields.assignee.emailAddress +``` + +
+ +:::note +If you already have a mapping configured you should append the new mapping to the existing one. +::: -## Install +## Install the plugin ```bash yarn --cwd packages/app add @port-labs/backstage-plugin-dev-daily diff --git a/docs/site/docs/features/_category_.json b/docs/site/docs/features/_category_.json index 324504768..e1c1956e5 100644 --- a/docs/site/docs/features/_category_.json +++ b/docs/site/docs/features/_category_.json @@ -1,4 +1,4 @@ { "label": "Features", - "position": 5 + "position": 6 } diff --git a/docs/site/docs/getting-started.md b/docs/site/docs/getting-started.md index 64d1cad86..748d61fb7 100644 --- a/docs/site/docs/getting-started.md +++ b/docs/site/docs/getting-started.md @@ -12,7 +12,7 @@ Let's discover **Port's Backstage plugin in less than 5 minutes**. - A Backstage instance - A Port account - - Visit [Port's website](https://www.getport.io) to create your **free** account. + - Visit [Port's website](https://app.getport.io) to create your **free** account. - Follow the onboarding process to set up your organization. ### Install Plugins @@ -75,6 +75,10 @@ import { SettingsPage } from "@port-labs/backstage-plugin-framework"; ; ``` +To view the settings page, click the **Settings** button on the bottom left and click on the **Port** tab. + +![Port Settings](/img/settings-page.png) + ## Example out-of-the-box plugin - Dev Daily Follow the [Dev Daily Plugin documentation](./examples/dev-daily.md) to learn how to use the Dev Daily Plugin. diff --git a/docs/site/docs/integrations/_category_.json b/docs/site/docs/integrations/_category_.json new file mode 100644 index 000000000..0563a646e --- /dev/null +++ b/docs/site/docs/integrations/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Integrations", + "position": 7 +} diff --git a/docs/site/docs/integrations/github.mdx b/docs/site/docs/integrations/github.mdx new file mode 100644 index 000000000..ce9223a87 --- /dev/null +++ b/docs/site/docs/integrations/github.mdx @@ -0,0 +1,12 @@ +--- +title: GitHub Integration +--- + +### Install GitHub Integration + +1. In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab. +2. Click on the **Add Integration** button, in the settings page. +3. In the **Git Providers** section, click on the **GitHub** button. +4. Follow the instructions to install the GitHub app on your GitHub account. + +Read more about Port's GitHub integration [here](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/git/github/#setup). diff --git a/docs/site/docs/integrations/jira.mdx b/docs/site/docs/integrations/jira.mdx new file mode 100644 index 000000000..d3824b62d --- /dev/null +++ b/docs/site/docs/integrations/jira.mdx @@ -0,0 +1,20 @@ +--- +title: Jira Integration +--- + +### Install Jira Integration + +1. First, obtain a [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) for the atlassian account you want to use to authenticate with Jira. +2. In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab. +3. Click on the **Add Integration** button, in the settings page. +4. Scroll down to **Project Management** and select **Jira**. +5. Fill out the form: + - **Name**: Give your integration a name. + - **Installation Method**: Select **Hosted by Port**. For more advanced setups, read [here](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/project-management/jira/?installation-methods=real-time-self-hosted#setup) + - **Jira Host**: Usually it's `https://.atlassian.net`. + - **Atlassian User Email**: The email of the user you want to use to authenticate with Jira. + - **Atlassian API Token**: The API Token you obtained for the user. +6. Click on the **Save** button. + +![Jira Integration](/img/jira-integration.png) +Read more about Port's Jira integration [here](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/project-management/jira/#setup). diff --git a/docs/site/static/img/jira-integration.png b/docs/site/static/img/jira-integration.png new file mode 100644 index 000000000..bc2a08b8b Binary files /dev/null and b/docs/site/static/img/jira-integration.png differ diff --git a/docs/site/static/img/settings-page.png b/docs/site/static/img/settings-page.png new file mode 100644 index 000000000..f47a0de02 Binary files /dev/null and b/docs/site/static/img/settings-page.png differ