diff --git a/docs/user/devops-pipelines.md b/docs/user/devops-pipelines.md index b8a16b11ab..6bcdc6a91b 100644 --- a/docs/user/devops-pipelines.md +++ b/docs/user/devops-pipelines.md @@ -8,7 +8,7 @@ navTitle: DevOps Pipelines **Navigation**: `Team > Application > Pipelines` - +![Overview of a DevOps Pipeline in FlowFuse](./images/ui-devops-pipelines.png){data-zoomable} In FlowFuse it is possible to configure a DevOps pipeline for your Node-RED instances. @@ -40,7 +40,7 @@ See [Pipeline Stage details](#pipeline-stage-details) below for more info. ## Running a Pipeline Stage - +![Running a pipeline stage by clicking the play icon on the source stage](./images/ui-devops-run.png){data-zoomable} Each stage currently is deployed manually. To do so, click the "play" icon on the source stage. In the example above, it will push from the "Development" stage to the "Production" stage. @@ -66,13 +66,12 @@ There are four types of stage to chose from: 1. **[Instance](./concepts.md#hosted-instance)** - a single Node-RED instance. 2. **[Device](./concepts.md#remote-instance)** - a single remote instance. 3. **[Device Group](./concepts.md#device-groups)** - a group of remote instances. -4. **Git Repository** - a remote GitHub/Azure DevOps repository. - - This stage currently only supports: - - Repositories hosted on GitHub.com or dev.azure.com +4. **Git Repository** - a remote Git repository. + - This stage supports GitHub, Azure DevOps, and any other Git server accessible over HTTPS (for example GitLab, Bitbucket, Gitea, or a self-hosted instance). ### Actions - +![Selecting an action for a pipeline stage](./images/ui-devops-select-action.png){data-zoomable} The action defines what happens when the stage is deployed. The available actions depend on the stage type selected for the stage. @@ -103,15 +102,59 @@ When a Device Group stage is triggered, it will push the current active snapshot #### Git Repository stage -Git Repository stages can be used to push and pull snapshots from a GitHub or Azure DevOps hosted repository. The stage can be configured with -the branch to push/pull from as well as the filename to use for the snapshot. +Git Repository stages can be used to push and pull snapshots to and from a remote Git repository. FlowFuse supports GitHub, Azure DevOps, and any other Git server that is accessible over HTTPS, for example GitLab, Bitbucket, Gitea, or a self-hosted instance. + +> This feature is available to Team and Enterprise tier teams on FlowFuse Cloud, and to Enterprise licensed self-hosted installations from version 2.32 onwards. Support for generic HTTPS Git servers (anything other than GitHub and Azure DevOps) requires version 2.32 or later. + +##### Adding a Git token + +Before you can create a Git Repository stage, you need to add a token that grants FlowFuse access to your repository. Tokens are managed per team, under `Team > Team Settings > Integrations`. + +1. Go to **Team Settings** and open the **Integrations** tab. +2. In the Git integration section, click **Add Token**. +3. In the **Add Git Personal Access Token** popup, choose the tab that matches your Git server (**GitHub**, **Azure DevOps**, or **Other**) and follow the instructions for that provider (below). +4. Give the token a **Name**, complete the required fields, and click **Add**. + +![Add Git Personal Access Token popup with tabs for GitHub, Azure DevOps, and Other providers](./images/generic-git-provider.png){data-zoomable} + +###### GitHub + +1. Open GitHub Personal Access Tokens Settings. +2. Click on **Generate a new token**. +3. Select the **Only select repositories** option and pick which repositories to grant access to. +4. Expand the **Repository permissions** section and ensure the **Contents** option is set to **Read and write**. +5. Click on **Generate token**. +6. This will be the only time GitHub shows you the token value. Copy the token into the **Token** field. + +###### Azure DevOps + +1. Open `https://dev.azure.com/[org-name]/_usersSettings/tokens` to create a new Personal Access Token. +2. Click the **+ New Token** button. +3. Give the token a name and set the **Expiry** date. +4. Select **Custom defined** for the Scopes. +5. Check **Read & Write** in the **Code** section. +6. Hit **Save**. +7. This will be the only time Azure shows you the token value. Copy the token into the **Token** field. + +###### Other + +Use this tab to connect to any Git server (GitLab, Bitbucket, Gitea, or a self-hosted instance) over HTTPS. + +1. Create a Personal Access Token (or App Password) on your Git server with read & write access to the repository. +2. Enter the **Username** associated with that token. +3. Paste the token value into the **Token** field. +4. **CA Certificate (optional)**: only needed for self-hosted servers that use a private certificate authority. Paste the certificate (in PEM format, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines) into this field so that FlowFuse can trust the connection. No changes to your infrastructure are required. + +##### Configuring the stage + +When adding a Git Repository stage, select the token you created and enter the repository URL (for example `https://github.com/your-org/nodered-flows.git`). The stage can be configured with the branch to push/pull from as well as the filename to use for the snapshot. If a filename is not configured, it will generate the filename when pushing to the repository based on the name of Instance, Device or Device Group that provided the snapshot. The provided filename can include directory structures, allowing the snapshot to be stored in a subdirectory of the repository. When pulling from a repository, if the stage has not previously been used to push to the repository, the filename is a required property. -It is also possible to configure the stage with different branches for the push and pull actions. This enables a GitHub-based review process as part of the pipeline; using a Pull Request process to review and approve the changes before merging between the two branches. +It is also possible to configure the stage with different branches for the push and pull actions. This enables a Git-based review process as part of the pipeline; using a Pull Request process to review and approve the changes before merging between the two branches. #### Deploy to Devices @@ -126,8 +169,8 @@ and updates to the flows can only be made by a Team Owner running a DevOps pipel Protected mode is activated under Instance > Settings > Protect Instance - +![The Protect Instance setting under Instance Settings](./images/protected-instance.png){data-zoomable} A Protected Instance will be marked by a status badge next to it's running state. Click on this badge will take you to the Settings page. - +![Protected status badge shown next to the instance running state](./images/protected-instance-pill.png){data-zoomable} diff --git a/docs/user/images/generic-git-provider.png b/docs/user/images/generic-git-provider.png new file mode 100644 index 0000000000..1e5cdeec30 Binary files /dev/null and b/docs/user/images/generic-git-provider.png differ diff --git a/docs/user/user-settings.md b/docs/user/user-settings.md index c42ebdf9d4..04a316ece4 100644 --- a/docs/user/user-settings.md +++ b/docs/user/user-settings.md @@ -15,6 +15,7 @@ In the Settings section, you can modify various characteristics of your personal - **Username** - **Name** - **E-Mail** (modifiable only if SSO is disabled) +- **Theme** - choose **Light**, **Dark**, or **System** for the FlowFuse interface. **System** follows your operating system setting and updates live when it changes. Your choice is saved per browser. This applies to the FlowFuse application only; the Node-RED editor and Dashboard manage their own themes separately. Additionally, you can select a default Team, especially useful if your account is associated with multiple Teams.