From 233cdb2975607141853da12d4b05036219692daf Mon Sep 17 00:00:00 2001 From: melody-universe Date: Wed, 30 Jun 2021 22:32:48 -0700 Subject: [PATCH] created first run at documentation --- .gitattributes | 1 + README.md | 68 ++++++++++++++++--- SUPPORT.md | 24 ++----- .../create-repository-from-template.png | 3 + .../one-application-user-secrets.png | 3 + .../two-application-users-secrets.png | 3 + 6 files changed, 73 insertions(+), 29 deletions(-) create mode 100644 readme-assets/create-repository-from-template.png create mode 100644 readme-assets/one-application-user-secrets.png create mode 100644 readme-assets/two-application-users-secrets.png diff --git a/.gitattributes b/.gitattributes index 19be302..79cf762 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,2 +1,3 @@ pac/**/* filter=lfs diff=lfs merge=lfs -text +/readme-assets/**/* filter=lfs diff=lfs merge=lfs -text pac/**/*.* filter=lfs diff=lfs merge=lfs -text diff --git a/README.md b/README.md index 5cd7cec..6b61107 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,64 @@ -# Project +# Power Apps Portals ALM Sample -> This repo has been populated by an initial template to help get you started. Please -> make sure to update the content to build a great experience for community-building. +This project provides a starting point for applying ALM best practices to your Power Apps Portals projects. It adopts two major tenets: -As the maintainer of this project, please make a few updates: +- Establish source control as the definitive source of truth +- Fully automate commits, builds, and deployments. -- Improving this README.MD file to provide a great experience -- Updating SUPPORT.MD with content about this project's support experience -- Understanding the security reporting process in SECURITY.MD -- Remove this section from the README +## Prerequisites + +- A GitHub account +- Access to two existing Dataverse environments (one for "development" and one for "production") + - **Note:** The environments do not both need to be in the same tenant. + - One [Dataverse starter portal](https://docs.microsoft.com/en-us/powerapps/maker/portals/create-portal) provisioned in each environment + - One [application user](https://docs.microsoft.com/en-us/power-platform/admin/manage-application-users) with the System Administrator role in each environment + - **Note:** You can either use a single application user for both environments (if they are in the same tenant) or a separate application user for each environment. +- (Optional) [GitHub Enterprise](https://docs.github.com/en/get-started/learning-about-github/githubs-products#github-enterprise) + +## Setup + +1. Either fork this repository or [use it as a template](https://github.com/microsoft/power-apps-portals-alm/generate). + ![Screenshot creating a new public repository using this one as a template](./readme-assets/create-repository-from-template.png) + - **Note:** Because this project uses [environments](https://docs.github.com/en/actions/reference/environments), you must create either a public repository or a private repository for GitHub Enterprise. +2. Set up the environments in your repository (outlined below): + 1. From your repository home page, click **Settings**. + 2. Click **Environments**. + 3. Click **New environment**. + 4. For the name, type _development_. Click **Configure environment**. + 5. Under **Environment secrets**, click **Add Secret**. + 6. For **Name**, type _URL_. + 7. For **Value**, provide the URL of your development environment, e.g. *https://my-awesome-dev.crm.dynamics.com/*. + 8. If you are using separate application users for each environment, or if you are using separate tenants, repeat steps 5-7 to create the following secrets: + - **APPLICATION_ID**: Application (client) ID of your application user, e.g. _01234567-89ab-cdef-0123-456789abcdef_ + - **CLIENT_SECRET**: A client secret for your application user, e.g. _1f7~GP48Pi17T-R.4uyIU7_kOiV2NCnH_Q_. + - **TENANT_ID**: The Directory (tenant) ID that your development environment is provisioned in, e.g. _fedcba98-7654-3210-fedc-ba9876543210_. + 9. Repeat steps 1-8 for your production environment. +3. If you are using a single application user for both environments, add its information to your repository as secrets (outlined below): + 1. In the left-hand navigation of your repository's Settings page, click **Secrets**. + 2. Click **New repository secret**. + 3. For **Name**, type _APPLICATION_ID_. + 4. For **Value**, provide the application (client) ID of your application user, e.g. _01234567-89ab-cdef-0123-456789abcdef_. + 5. Repeat steps 2-4 to create the following secrets: + - **CLIENT_SECRET**: A client secret for your application user, e.g. _1f7~GP48Pi17T-R.4uyIU7_kOiV2NCnH_Q_. + - **TENANT_ID**: The Directory (tenant) ID that your development environment is provisioned in, e.g. _fedcba98-7654-3210-fedc-ba9876543210_. + +When you're finished with steps 2-3, your Secrets page should look like one of the following: + +- If you are using a single application user for both environments: + ![Screenshot of Secrets page with two environment secrets and three repository secrets](./readme-assets/one-application-user-secrets.png) +- If you are using one application user per environment: + ![Screenshot of Secrets page with eight environment secrest and no repository secrets](./readme-assets/two-application-users-secrets.png) + +4. Run the **Provision Dev** workflow (outlined below): + 1. Click **Actions**. + 2. Click **Provision Dev**. + 3. Click **Run workflow** > **Run workflow**. + +5. (Optional) Using the same steps outlined in step 4, run the **CI/CD** workflow. ## Contributing -This project welcomes contributions and suggestions. Most contributions require you to agree to a +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. @@ -26,8 +72,8 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio ## Trademarks -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft -trademarks or logos is subject to and must follow +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft +trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies. diff --git a/SUPPORT.md b/SUPPORT.md index dc72f0e..96cf9ea 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,25 +1,13 @@ -# TODO: The maintainer of this repo has not yet edited this file - -**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project? - -- **No CSS support:** Fill out this template with information about how to file issues and get help. -- **Yes CSS support:** Fill out an intake form at [aka.ms/spot](https://aka.ms/spot). CSS will work with/help you to determine next steps. More details also available at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). -- **Not sure?** Fill out a SPOT intake as though the answer were "Yes". CSS will help you decide. - -*Then remove this first heading from this SUPPORT.MD file before publishing your repo.* - # Support -## How to file issues and get help +## How to file issues and get help -This project uses GitHub Issues to track bugs and feature requests. Please search the existing -issues before filing new issues to avoid duplicates. For new issues, file your bug or +This project uses GitHub Issues to track bugs and feature requests. Please search the existing +issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new Issue. -For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE -FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER -CHANNEL. WHERE WILL YOU HELP PEOPLE?**. +For help and questions about using this project, please contact [Melody Hogsett](mailto:mhogsett@microsoft.com). -## Microsoft Support Policy +## Microsoft Support Policy -Support for this **PROJECT or PRODUCT** is limited to the resources listed above. +Support for this project is limited to the resources listed above. diff --git a/readme-assets/create-repository-from-template.png b/readme-assets/create-repository-from-template.png new file mode 100644 index 0000000..525525a --- /dev/null +++ b/readme-assets/create-repository-from-template.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2816a98fe99ea7ba037ccd22ffcf9d7e68318d7352538e0c429f36cde048e3ce +size 130878 diff --git a/readme-assets/one-application-user-secrets.png b/readme-assets/one-application-user-secrets.png new file mode 100644 index 0000000..a25c1af --- /dev/null +++ b/readme-assets/one-application-user-secrets.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f433a1071ae70d50cdb3aac96923fa1ab302ba271e0a94150dfb69bac77ecedd +size 88866 diff --git a/readme-assets/two-application-users-secrets.png b/readme-assets/two-application-users-secrets.png new file mode 100644 index 0000000..0586f6e --- /dev/null +++ b/readme-assets/two-application-users-secrets.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:54f66339ee651353a25aafb3d4f2c1a9d1ab8360497ab1fff9c740a66d2a86f4 +size 179406