2 |
3 | # Welcome to Tugboat!
4 |
5 | Tugboat is a system that builds a working preview of a website for any branch, tag, commit, or pull request in a git
6 | repository. It can automatically create these previews for pull requests by integrating with GitHub, GitLab, or
7 | Bitbucket git repositories.
8 |
9 | This document aims to provide the information required to use Tugboat. It includes tutorials, examples, and references
10 | for all experience levels.
11 |
12 | ## Contributing
13 |
14 | This document is open-source, and is available on [GitHub](https://github.com/TugboatQA/docs). If you have any
15 | suggestions or other feedback about this document, we are happy to hear it!
16 | [Open a GitHub issue](https://github.com/TugboatQA/docs/issues/new) or email us at
17 | [support@tugboatqa.com](mailto:support@tugboatqa.com).
18 |
19 | ## Theme
20 |
21 | The [Hugo Learn Theme](https://github.com/matcornic/hugo-theme-learn) is included in this repo as a git subtree. To
22 | update the theme, find the latest tag at https://github.com/matcornic/hugo-theme-learn/releases and run the following
23 |
24 | ```sh
25 | export TAG=2.4.0
26 | git subtree pull --prefix themes/hugo-theme-learn https://github.com/matcornic/hugo-theme-learn.git $TAG --squash
27 | ```
28 |
29 | ## Redirects
30 |
31 | Redirects for historic URLs are maintained in `static/.htaccess`. These can be tested using
32 | [Smolder](https://github.com/sky-shiny/smolder) config file in `test/smolder.yaml`. The tests need to be run against a
33 | live instance, like a Tugboat preview.
34 |
35 | ```sh
36 | cat test/smolder.yaml | docker run -i mcameron/smolder pr125-mcktkhcj8krhxo5oaa7emgv5gcnf5e5l.tugboatqa.com
37 | ```
38 |
39 | ## License Information
40 |
41 | This document is licensed as
42 | [Creative Commons Attribution-NonCommercial-ShareAlike CC BY-NC-SA](http://creativecommons.org/licenses/by-nc-sa/4.0/legalcode).
43 |
44 | Everything not covered above is licensed under the [MIT license](https://choosealicense.com/licenses/mit/).
45 |
--------------------------------------------------------------------------------
/content/setting-up-tugboat/add-repos-to-the-project.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Add Repos to the Project"
3 | date: 2019-09-17T11:42:01-04:00
4 | weight: 3
5 | ---
6 |
7 | Once you've decided how you want to structure your project, add the relevant repos to your project.
8 |
9 | ### To add repos during project creation:
10 |
11 | When you're creating a project, select your repository host from the Provider drop-down, select the Organization, if
12 | applicable, and click the radio button next to the repo you want to add.
13 |
14 | 
15 |
16 | Alternately, if you're using a generic git server, select Git as the provider, and enter your Git URL.
17 |
18 | 
19 |
20 | ### To add repos to a project you've already created:
21 |
22 | 1. Go to username -> [My Projects](https://dashboard.tugboatqa.com/projects) at the upper-right of the Tugboat screen.
23 | 2. Select the project where you want to add the repo.
24 | 3. Go to {{% ui-text %}}Add a Repository{{% /ui-text %}} .
25 |
26 | From there, you'll be back to the 'select a provider and specify a repo' screen.
27 |
28 | {{% notice info %}} There is no limit to the number of repositories you can add to a Tugboat project. However, you may
29 | be unable to build new Previews within a project, if the total storage used in your project reaches the
30 | [billing tier storage limit for your project](/tugboat-billing/tugboat-pricing/#how-does-tugboat-pricing-work).
31 | {{% /notice %}}
32 |
33 | {{%expand "Visual Walkthrough" %}}
34 |
35 | Go to username -> [My Projects](https://dashboard.tugboatqa.com/projects) at the upper-right of the Tugboat screen.
36 |
37 | 
38 |
39 | Select the project where you want to add the repo.
40 |
41 | 
42 |
43 | Go to {{% ui-text %}}Add a Repository{{% /ui-text %}} .
44 |
45 | 
46 |
47 | From there, you'll be back to the 'select a provider and specify a repo' screen.
48 |
49 | {{% /expand%}}
50 |
--------------------------------------------------------------------------------
/content/manage-users/user-admin.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "User Permission Levels"
3 | date: 2019-09-19T10:36:14-04:00
4 | lastmod: 2020-04-17T17:00:00-04:00
5 | weight: 4
6 | aliases:
7 | - "/administer-tugboat-crew/user-admin"
8 | ---
9 |
10 | ### User permission levels explained
11 |
12 | Tugboat has four different types of users:
13 |
14 | - [Owner](#owner-permissions)
15 | - [Admin](#admin-permissions)
16 | - [User](#user-permissions)
17 | - [Read-only](#read-only-permissions)
18 |
19 | #### Owner permissions
20 |
21 | Owner users can:
22 |
23 | - Manage billing information. This information is disabled if the company is paying with a purchase order.
24 |
25 | Owners can also do everything the [admin user](#admin-permissions) and [general user](#user-permissions) can do.
26 |
27 | #### Admin permissions
28 |
29 | Admin users can:
30 |
31 | - Add and remove users from a project, and change user permissions. Admin users can administer other admin users, though
32 | they cannot remove themselves from a project.
33 | - Add repositories to the project.
34 | - Manage the repository configuration interface. This includes things like
35 | [changing repository settings](/setting-up-tugboat/select-repo-settings/#change-repository-settings), environment
36 | variables and SSH keys.
37 | - Delete repositories.
38 | - Delete the entire project.
39 | - Rename the project.
40 |
41 | Admin can also do everything the [general user](#user-permissions) can do.
42 |
43 | #### User permissions
44 |
45 | Tugboat's general User's permissions include:
46 |
47 | - View the repository configuration interface. This includes things like
48 | [repository settings](/setting-up-tugboat/select-repo-settings/#change-repository-settings), environment variables and
49 | SSH keys.
50 | - Manage Previews. Create, remove, rebuild, or lock Previews.
51 | - Manage Base Previews.
52 | - Shell access to previews. Manage visual diff screenshots. View build logs.
53 |
54 | #### Read-only permissions
55 |
56 | Tugboat users with Read-only permissions can:
57 |
58 | - View a list of all Previews, see build logs and visual diff screenshots.
59 | - Read-only users may create additional visual diff screenshots.
60 |
61 | These users have no access to anything else.
62 |
--------------------------------------------------------------------------------
/content/tugboat-billing/change-billing-information.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Change Billing Information"
3 | date: 2019-09-19T10:49:50-04:00
4 | weight: 3
5 | ---
6 |
7 | {{% notice tier %}} The following instructions do not apply to subscriptions to
8 | [Tugboat Premium](https://www.tugboatqa.com/pricing). For those subscriptions, please contact your Tugboat account
9 | executive or [Tugboat Support](https://www.tugboatqa.com/support). {{% /notice %}}
10 |
11 | ## To change the billing information for your Tugboat project:
12 |
13 | 1. Go to username -> [My Projects](https://dashboard.tugboatqa.com/projects) at the upper-right of the Tugboat
14 | dashboard.
15 | 2. Select the project where you want to change the billing info.
16 | 3. Go to {{% ui-text %}}Project Settings{{% /ui-text %}}.
17 | 4. Scroll down to {{% ui-text %}}Your Plan{{% /ui-text %}}.
18 | 5. Click the {{% ui-text %}}Billing Information{{% /ui-text %}} link.
19 |
20 | From here, you can:
21 |
22 | - Edit the email address associated with billing for the Tugboat project
23 | - Edit the payment method
24 | - View or print invoices
25 |
26 | {{%expand "Visual Walkthrough" %}}
27 |
28 | Go to username -> [My Projects](https://dashboard.tugboatqa.com/projects) at the upper-right of the Tugboat dashboard.
29 |
30 | 
31 |
32 | Select the project where you want to change the billing info.
33 |
34 | 
35 |
36 | Go to {{% ui-text %}}Project Settings{{% /ui-text %}}.
37 |
38 | 
39 |
40 | Scroll down to {{% ui-text %}}Your Plan{{% /ui-text %}}.
41 |
42 | 
43 |
44 | Click the {{% ui-text %}}Billing Information{{% /ui-text %}} link.
45 |
46 | 
47 |
48 | From here, you can:
49 |
50 | - Edit the email address associated with billing for the Tugboat project
51 | - Edit the payment method
52 | - View or print invoices
53 |
54 | 
55 |
56 | {{% /expand%}}
57 |
--------------------------------------------------------------------------------
/content/third-party-integrations/slack-integration.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Slack Webhook Integration"
3 | date: 2021-04-29T10:00:00-04:00
4 | weight: 20
5 | aliases:
6 | - /starter-configs/code-snippets/slack-integration
7 | ---
8 |
9 | Incoming Webhooks are a simple way to post messages from Tugboat into [Slack](https://slack.com/). Creating an Incoming
10 | Webhook gives you a unique URL to which you send a JSON payload with the message text and some options.
11 |
12 | ## Prerequisites: Slack and GitHub
13 |
14 | 1. So, you'll need a [GitHub](https://github.com/) repository, a [Slack](https://slack.com/) account and workspace, and
15 | Tugboat account and project.
16 | 2. You'll need to [create a Slack App](https://api.slack.com/messaging/webhooks) from within your Slack account, and
17 | enable _Incoming Webhooks_.
18 | 3. In the Slack app settings, and you should now see a new entry under the _Webhook URLs for Your Workspace section_,
19 | with a Webhook URL. Copy that URL. We'll import it into Tugboat as an environment variable. The URL will look
20 | something like: `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`
21 |
22 | ## Tugboat Repository Configuration
23 |
24 | Create a Tugboat [environment variable](/setting-up-services/how-to-set-up-services/custom-environment-variables/) to
25 | store your `SLACK_WEBHOOK_URL`:
26 |
27 | ## Tugboat config.yml
28 |
29 | Use this snippet in your [configuration file](/setting-up-tugboat/create-a-tugboat-config-file/) to communicate with
30 | Slack via the [service](/setting-up-services/) you want to respond from.
31 |
32 | ```yaml
33 | services:
34 | apache:
35 | commands:
36 | online:
37 | # Send a slack notification if we're on a PR build
38 | - |
39 | if [ ! -z "${TUGBOAT_GITHUB_PR}" ]; then
40 | PR_URL="https://github.com/$TUGBOAT_REPO/pull/$TUGBOAT_GITHUB_PR"
41 | DASHBOARD_URL="https://dashboard.tugboatqa.com/$TUGBOAT_PREVIEW_ID"
42 | MESSAGE="*Tugboat URL:* $TUGBOAT_SERVICE_URL\n*PR:* $PR_URL\n*Dashboard:* $DASHBOARD_URL"
43 | curl -X POST --data-urlencode "payload={\"username\": \"Tugboat\", \"text\": \"$MESSAGE\", \":boat:\": \":tugboat_qa:\"}" "$SLACK_WEBHOOK_URL"
44 | fi
45 | ```
46 |
47 | Voila! You Slack integration will look like this:
48 |
49 | 
50 |
--------------------------------------------------------------------------------
/content/starter-configs/examples/static-html.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Static HTML"
3 | date: 2019-09-19T11:00:39-04:00
4 | weight: 1
5 | ---
6 |
7 | A static HTML Tugboat Preview serves files exactly as they are found in the git repository.
8 |
9 | ## Configure Tugboat
10 |
11 | The Tugboat configuration is managed by a [YAML file](/setting-up-tugboat/create-a-tugboat-config-file/) at
12 | `.tugboat/config.yml` in the git repository. Here's a basic static HTML configuration you can use as a starting point,
13 | with comments to explain what's going on:
14 |
15 | ```yaml
16 | services:
17 | # What to call the service hosting the site. Because there is only
18 | # one service, it is automatically set as the default service, which
19 | # does a few things
20 | # 1. Clones the git repository into the service container
21 | # 2. Exposes port 80 to the Tugboat HTTP proxy
22 | # 3. Routes requests to the preview URL to this service
23 | apache:
24 | # Use the available version of Apache by not specifying a version
25 | image: tugboatqa/httpd
26 |
27 | # A set of commands to run while building this service
28 | commands:
29 | # Commands that set up the basic preview infrastructure
30 | init:
31 | # Link the document root to the expected path. This example links the
32 | # root of the git repository to the docroot
33 | - ln -snf "${TUGBOAT_ROOT}" "${DOCROOT}"
34 | ```
35 |
36 | Want to know more about something mentioned in the comments of this config file? Check out these topics:
37 |
38 | - [Name your Service](/setting-up-services/how-to-set-up-services/name-your-service/)
39 | - [Specify a Service image](/setting-up-services/how-to-set-up-services/specify-a-service-image/)
40 | - [Leverage Service commands](/setting-up-services/how-to-set-up-services/leverage-service-commands/)
41 | - [Define a default Service](/setting-up-services/how-to-set-up-services/define-a-default-service/)
42 | - [Set the document root path](/setting-up-services/how-to-set-up-services/set-the-document-root-path/)
43 | - [Preview build process phases (`init`, `update`, `build`)](/building-a-preview/preview-deep-dive/how-previews-work/#the-build-process-explained)
44 |
45 | ## Start Building Previews!
46 |
47 | Once this Tugboat configuration file is committed to your git repository, you can start
48 | [building previews](/building-a-preview/administer-previews/build-previews/)!
49 |
--------------------------------------------------------------------------------
/content/faq/compatible-technologies.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Compatible Technologies"
3 | date: 2019-09-26T15:23:53-04:00
4 | weight: 1
5 | ---
6 |
7 | ## Does Tugboat work with...?
8 |
9 | Tugboat supports pretty much anything that runs on Linux. Look through our
10 | [prebuilt service images](/reference/tugboat-images/) to see what we currently have available. If something that you
11 | need is missing, let us know, and we will work with you to get it added to the list.
12 |
13 | People frequently ask about whether Tugboat works with these technologies:
14 |
15 | - **Acquia Cloud?** Yes!
16 | - **Pantheon?** Yes! We even have a [tutorial](/starter-configs/tutorials/pantheon/) to show you how.
17 | - **GitHub, GitLab, BitBucket?** Yes! Check out:
18 | [Setting up Tugboat -> Connect with your git provider](/setting-up-tugboat/connect-with-your-provider/)
19 | - **Self-hosted git repositories?** Yes! See:
20 | [Setting up Tugboat -> Generic git server](/setting-up-tugboat/connect-with-your-provider/#generic-git-server)
21 | - **My own images?** Yes! See:
22 | [Setting up Services -> Specify a Service image](/setting-up-services/how-to-set-up-services/specify-a-service-image/)
23 | - **My existing database?** Yes! Take a look at
24 | [Starter Configs -> Import a MySQL Database](/starter-configs/code-snippets/import-mysql-database/) for an example.
25 |
26 | ## Does Tugboat have a Slack integration?
27 |
28 | Tugboat does not currently have a direct Slack integration. However, you can get very similar functionality if you're
29 | using a git integration with Slack:
30 |
31 | - [GitHub for Slack](https://github.com/integrations/slack)
32 | - [GitLab Slack Application](https://docs.gitlab.com/ee/user/project/integrations/gitlab_slack_application.html)
33 | - [BitBucket Cloud for Slack](https://confluence.atlassian.com/bitbucket/bitbucket-cloud-for-slack-945096776.html)
34 |
35 | With one of these integrations configured, use
36 | [Tugboat's Repository Settings for git provider integrations](/setting-up-tugboat/select-repo-settings/#modify-settings-for-your-github-gitlab-or-bitbucket-integration)
37 | to share details about your Tugboat Previews, such as:
38 |
39 | - Set Pull Request Status
40 | - Set Pull Request Deployment Status
41 | - Post Preview Links in Pull Request Comments
42 |
43 | When using these settings, Tugboat's updates to your git repository can be carried through your git Slack integration
44 | into your relevant Slack channels.
45 |
--------------------------------------------------------------------------------
/content/third-party-integrations/jira.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Jira Environment Mapping"
3 | date: 2025-05-13T11:00:00-04:00
4 | weight: 40
5 | ---
6 |
7 | Integrate Tugboat with [Jira](https://www.atlassian.com/software/jira) using the
8 | [GitHub for Jira](https://github.com/atlassian/github-for-jira/blob/main/docs/deployments.md#environment-mapping) plugin
9 | to map your deployment environments. This ensures that deployments from Tugboat (and other environments) are displayed
10 | with the correct labels in Jira, making it easier to track where your code is running.
11 |
12 | ## Prerequisites
13 |
14 | - A GitHub repository with
15 | [environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)
16 | set up (e.g., Dev, Test, Tugboat, Production Host).
17 | - Jira Cloud instance with the [GitHub for Jira](https://github.com/atlassian/github-for-jira) app installed and
18 | connected to your GitHub organization.
19 |
20 | ## Configure Environment Mapping
21 |
22 | By default, Jira may show deployments as "unmapped" unless you configure environment mapping. To fix this:
23 |
24 | 1. **Add a `.jira/config.yml` file to your repository root:**
25 |
26 | ```yaml
27 | deployments:
28 | environmentMapping:
29 | development:
30 | - "Dev"
31 | testing:
32 | - "Tugboat"
33 | staging:
34 | - "Test"
35 | production:
36 | - "Production Host"
37 | ```
38 |
39 | - Deployments to **Dev** will show as **Development** in Jira.
40 | - Deployments to **Tugboat** will show as **Testing** in Jira.
41 | - Deployments to **Test** will show as **Staging** in Jira.
42 | - Deployments to **Production Host** will show as **Production** in Jira.
43 |
44 | _Tip: Adjust the mapping to fit your workflow. For example, if you consider Tugboat a staging environment, map it
45 | under `staging` instead of `testing`._
46 |
47 | 2. **Result in Jira**
48 |
49 | Once configured, deployments will appear in Jira under the correct environment labels. For example, a deployment to
50 | Tugboat will show up as "Testing" in Jira.
51 |
52 | 
53 |
54 | ## References
55 |
56 | - [GitHub for Jira: Environment Mapping Documentation](https://github.com/atlassian/github-for-jira/blob/main/docs/deployments.md#environment-mapping)
57 | - [Original Issue Discussion](https://github.com/TugboatQA/docs/issues/394)
58 |
--------------------------------------------------------------------------------
/content/setting-up-services/service-images/image-version-tags.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Docker Image Version Tags Primer"
3 | date: 2019-09-19T13:20:53-04:00
4 | weight: 1
5 | ---
6 |
7 | Use tags to indicate specific versions of an image, if needed. In
8 | [our how to call a Service image from Docker Hub example](/setting-up-services/how-to-set-up-services/specify-a-service-image/#how-to-call-a-service-image-from-docker-hub),
9 | we called:
10 |
11 | ```yaml
12 | services:
13 | apache:
14 | image: tugboatqa/httpd:2.4
15 | mysql:
16 | image: tugboatqa/mysql:5.6
17 | ```
18 |
19 | In this example, we called versions `2.4` and `5.6` for the `httpd` and `mysql` images. These are Docker image version
20 | tags.
21 |
22 | You can specify version tags in a few different ways:
23 |
24 | - [Point-release version tags](#point-release-version-tags)
25 | - [Major version tags](#major-version-tags)
26 | - [Latest version tags](#latest-version-tags)
27 |
28 | {{% notice note %}} If you don't need a specific version of a Service image, you can leave the tag off of the image
29 | call. When you don't specify a tag, you'll get the latest version of that image. However, because `latest` pulls the
30 | newest version of an image, it could introduce a breaking change, so we recommend specifying major/minor versions as
31 | needed. {{% /notice %}}
32 |
33 | If you're not sure which version tag to use, you can always browse to the service image on
34 | [Docker Hub](https://hub.docker.com/) and check out what tags are available.
35 |
36 | 
37 |
38 | ## Point-release version tags:
39 |
40 | Using specific version tags helps prevent breaking changes that come along with incremental updates. In our example
41 | above, we've called `tugboatqa/mysql:5.6` instead of `tugboatqa/mysql:5`.
42 |
43 | ## Major version tags
44 |
45 | If you want to make sure you're using a specific major version, but don't care about point releases, specify something
46 | like `tugboatqa/node:10` to ensure you always use the latest available minor release of node 10.x.
47 |
48 | ## Latest version tags
49 |
50 | In some cases, you're less likely to be worried about a specific version; for example, it may not matter which version
51 | of memcached you use.
52 |
53 | When you don't need to call for a specific version of a Service, using the image name without a tag
54 | (`tugboatqa/memcached`), or the `latest` tag (`tugboatqa/memcached:latest`) will get you the most recent version of a
55 | Service image.
56 |
--------------------------------------------------------------------------------
/content/building-a-preview/share-a-preview/auto-share-url.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Auto Share Preview URLs"
3 | date: 2019-09-24T11:56:56-04:00
4 | weight: 3
5 | ---
6 |
7 | When you're using the Tugboat integration with [GitHub](/setting-up-tugboat/connect-with-your-provider/#github),
8 | [GitLab](/setting-up-tugboat/connect-with-your-provider/#gitlab) or
9 | [BitBucket](/setting-up-tugboat/connect-with-your-provider/#bitbucket), you can configure Tugboat to automatically post
10 | links to Previews as comments on pull requests.
11 |
12 | ### To configure Tugboat to automatically post Preview links:
13 |
14 | 1. Go to username -> [My Projects](https://dashboard.tugboatqa.com/projects) at the upper-right of the Tugboat screen.
15 | 2. Select the project where you want Tugboat to auto-post Preview links.
16 | 3. Click into {{% ui-text %}}Settings{{% /ui-text %}} for the repository.
17 | 4. Click the checkbox for {{% ui-text %}}Post Preview Links in Pull Request Comments{{% /ui-text %}} .
18 | 5. Press the {{% ui-text %}}Save Configuration{{% /ui-text %}} button to save your changes.
19 |
20 | {{% notice note %}} By default, Tugboat's comments to a linked git provider display as the person who linked the
21 | provider to Tugboat. That means the person who linked the repo will get notifications for every PR where Tugboat
22 | automatically posts a comment. If this person does not wish to receive notifications, you can
23 | [configure a Tugboat bot](/administer-tugboat-crew/add-tugboat-bot-to-team) to post the comments and receive those
24 | notifications. {{% /notice %}}
25 |
26 | {{%expand "Visual Walkthrough" %}}
27 |
28 | Go to username -> [My Projects](https://dashboard.tugboatqa.com/projects) at the upper-right of the Tugboat screen.
29 |
30 | 
31 |
32 | Select the project where you want Tugboat to auto-post Preview links.
33 |
34 | 
35 |
36 | Click into {{% ui-text %}}Settings{{% /ui-text %}} for the repository.
37 |
38 | 
39 |
40 | Click the checkbox for {{% ui-text %}}Post Preview Links in Pull Request Comments{{% /ui-text %}} .
41 |
42 | 
43 |
44 | Press the {{% ui-text %}}Save Configuration{{% /ui-text %}} button to save your changes.
45 |
46 | 
47 |
48 | {{% /expand%}}
49 |
--------------------------------------------------------------------------------
/.github/workflows/validate-configs.yml:
--------------------------------------------------------------------------------
1 | name: Validate TugboatQA/tugboat-test configs against schema
2 |
3 | on:
4 | pull_request:
5 | paths:
6 | - '.github/workflows/validate-configs.yml'
7 | - 'static/config-schema.json'
8 | workflow_dispatch:
9 |
10 | jobs:
11 | validate:
12 | runs-on: ubuntu-latest
13 | steps:
14 | - name: Checkout schema repository
15 | uses: actions/checkout@v4
16 | with:
17 | path: schema-repo
18 |
19 | - name: Checkout test repository
20 | uses: actions/checkout@v4
21 | with:
22 | repository: TugboatQA/tugboat-test
23 | path: test-repo
24 | fetch-depth: 0
25 |
26 | - name: Setup Node.js
27 | uses: actions/setup-node@v4
28 | with:
29 | node-version: '20'
30 |
31 | - name: Install ajv-cli
32 | run: |
33 | npm install -g ajv-cli@5.0.0
34 |
35 | - name: Validate configs
36 | working-directory: test-repo
37 | run: |
38 | # Get all remote branches
39 | git ls-remote --heads https://github.com/TugboatQA/tugboat-test.git | sed 's|^.*refs/heads/||' | while read -r branch; do
40 | echo "::group::Checking branch: $branch"
41 |
42 | # Checkout branch
43 | git checkout "$branch"
44 |
45 | # If config.yml exists, validate it
46 | if [ -f .tugboat/config.yml ]; then
47 | echo "Validating config.yml in branch $branch"
48 | if [ "$branch" = "yaml-fail" ] || [ "$branch" = "invalid-yaml" ]; then
49 | # For yaml-fail and invalid-yaml branches, we expect validation to fail
50 | if ajv validate --all-errors -s ../schema-repo/static/config-schema.json -d .tugboat/config.yml; then
51 | echo "::error::Branch $branch was expected to fail validation but passed"
52 | exit 1
53 | else
54 | echo "Branch $branch failed validation as expected"
55 | fi
56 | else
57 | # For all other branches, validation should pass
58 | if ! ajv validate --all-errors -s ../schema-repo/static/config-schema.json -d .tugboat/config.yml; then
59 | echo "::error::Schema validation failed for branch $branch"
60 | exit 1
61 | fi
62 | fi
63 | else
64 | echo "::warning::No config.yml found in branch $branch"
65 | fi
66 | echo "::endgroup::"
67 | done
--------------------------------------------------------------------------------
/content/tugboat-cli/set-an-access-token.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Set an Access Token"
3 | date: 2019-09-19T10:41:45-04:00
4 | weight: 2
5 | ---
6 |
7 | The first time you attempt to access a Tugboat resource in the Command Line Interface, you'll be asked for an Access
8 | Token.
9 |
10 | To set an Access Token:
11 |
12 | 1. In Tugboat's web interface, go to User Name -> Access Tokens, or
13 | [click this link](https://dashboard.tugboatqa.com/access-tokens).
14 | 2. Click the {{% ui-text %}}Generate New Token option{{% /ui-text %}}.
15 | 3. You'll be asked to give the Access Token a description; for example, "Command Line Tool"; enter a description and
16 | press the {{% ui-text %}}Generate{{% /ui-text %}} button.
17 | 4. Make sure you save your Access Token somewhere safe, such as [1Password](https://1password.com/) or other password
18 | manager.
19 | 5. When you run the CLI, and attempt to access a resource, you'll be asked for an Access Token; paste it in and hit `Y`
20 | to remember it.
21 |
22 | {{% notice tip %}} 1Password users can install
23 | [a shell plugin for the 1Password CLI](https://developer.1password.com/docs/cli/shell-plugins/tugboat) so that your
24 | Tugboat token will be encrypted, stored securely, and accessible from any machine. Thank you to Mark Dorison of
25 | [Chromatic](https://chromatichq.com) for contributing this plugin. {{% /notice %}}
26 |
27 | Now you're all set to use the Tugboat Command Line Interface!
28 |
29 | {{%expand "Visual Walkthrough" %}}
30 |
31 | In Tugboat's web interface, go to User Name -> Access Tokens, or
32 | [click this link](https://dashboard.tugboatqa.com/access-tokens).
33 |
34 | 
35 |
36 | Click the {{% ui-text %}}Generate New Token{{% /ui-text %}} option.
37 |
38 | 
39 |
40 | You'll be asked to give the Access Token a description; for example, "Command Line Tool"; enter a description and press
41 | the {{% ui-text %}}Generate{{% /ui-text %}} button.
42 |
43 | 
44 |
45 | Make sure you save your Access Token somewhere safe, as you won't be able to see it again!
46 |
47 | 
48 |
49 | When you run the CLI, and attempt to access a resource, you'll be asked for an Access Token; paste it in and hit `Y` to
50 | have the CLI remember it.
51 |
52 | 
53 |
54 | {{% /expand%}}
55 |
--------------------------------------------------------------------------------
/content/visual-diffs/view-visual-diffs.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "View Visual Diffs"
3 | date: 2019-09-26T15:30:03-04:00
4 | lastmod: 2020-12-22T11:30:00-04:00
5 | weight: 2
6 | ---
7 |
8 | To view Visual Diffs, you'll need to go to the Preview Dashboard.
9 |
10 | ## To view Visual Diffs:
11 |
12 | 1. Click into a Preview that has finished building.
13 | 2. Scroll down past the Services and Lighthouse Reports, and you'll see the Visual Diffs pane.
14 | 3. Click into the Visual Diff for Mobile, Tablet or Desktop to see the diff.
15 |
16 | Inside the diff, you'll see a **Before** visualization on the left, an **After** visualization on the right, and a
17 | composite in the middle, which highlights changes to the page.
18 |
19 | You'll also see an option to {{% ui-text %}}Regenerate{{% /ui-text %}} visual diffs; use this if you've updated your
20 | Base Preview, and want to see a new version of the visual diffs for this build.
21 |
22 | {{% notice info %}} While the Preview is building, you'll see: "Unavailable while preview is building" in the Visual
23 | Diffs pane. After the Preview build has completed, it will take some time for visual diffs to generate. If you get an
24 | error message, or don't see what you expect when the visual diffs generate, head over to
25 | [Troubleshooting -> Visual Diffs](/troubleshooting/preview-built-problem/#troubleshooting-visual-diffs) for tips on
26 | figuring out what happened. {{% /notice %}}
27 |
28 | {{%expand "Visual Walkthrough" %}}
29 |
30 | Click into a Preview that has finished building;
31 |
32 | 
33 |
34 | Scroll down past the Services and Lighthouse Reports, and you'll see the Visual Diffs pane;
35 |
36 | 
37 |
38 | Click into the Visual Diff for **Mobile**, **Tablet** or **Desktop** to see the diff.
39 |
40 | 
41 |
42 | Inside the diff, you'll see a **Before** visualization on the left, an **After** visualization on the right, and a
43 | composite in the middle, which highlights changes to the page.
44 |
45 | 
46 |
47 | You'll also see an option to {{% ui-text %}}Regenerate{{% /ui-text %}} visual diffs; use this if you've updated your
48 | Preview or Base Preview, and want to see a new version of the visual diffs for this build.
49 |
50 | 
51 |
52 | {{% /expand%}}
53 |
--------------------------------------------------------------------------------
/content/lighthouse/view-lighthouse-reports.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "View Lighthouse Reports"
3 | date: 2020-09-23T15:30:03-04:00
4 | weight: 2
5 | ---
6 |
7 | When you configure Tugboat to generate Google Lighthouse reports for your web app or website, you'll see a Lighthouse
8 | Reports status on your pull requests. You can click the **Details** link to go directly to the Lighthouse reports in the
9 | Tugboat Preview Dashboard.
10 |
11 | 
12 |
13 | Alternately, to view Lighthouse reports from within Tugboat, here's how to get to the Preview Dashboard:
14 |
15 | ## To view Lighthouse reports:
16 |
17 | 1. Click into a Preview that has finished building.
18 | 2. Scroll down past the Services and you'll see the Lighthouse Reports pane.
19 | 3. Click into one of the numbers to view the specifics for that category's audit, or click the Details link to view the
20 | full Lighthouse report.
21 |
22 | Inside the Lighthouse report, you'll see a list of audit items that were checked to provide your score. For more
23 | information on what you'll see in Lighthouse reports, take a look at:
24 | [Using Lighthouse -> What do Lighthouse reports measure?](../using-lighthouse/#what-do-lighthouse-reports-measure)
25 |
26 | You'll also see an option to {{% ui-text %}}Regenerate{{% /ui-text %}} Lighthouse reports.
27 |
28 | {{% notice info %}} While the Preview is building, you'll see: "Unavailable while preview is building" in the Lighthouse
29 | Reports pane. After the Preview build has completed, the Lighthouse reports will generate. {{% /notice %}}
30 |
31 | {{%expand "Visual Walkthrough" %}}
32 |
33 | Click into a Preview that has finished building;
34 |
35 | 
36 |
37 | Scroll down past the Services, and you'll see the Lighthouse Reports pane;
38 |
39 | 
40 |
41 | Click into one of the numbers to view the specifics for that category's audit, or click the Details link to view the
42 | full Lighthouse report.
43 |
44 | 
45 |
46 | Inside the Lighthouse report, you'll see a list of audit items that were checked to provide your score.
47 |
48 | 
49 |
50 | You'll also see an option to {{% ui-text %}}Regenerate{{% /ui-text %}} Lighthouse reports.
51 |
52 | 
53 |
54 | {{% /expand%}}
55 |
--------------------------------------------------------------------------------
/content/setting-up-services/service-images/docker-pull.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Docker Pull under the hood"
3 | date: 2019-09-19T13:22:39-04:00
4 | weight: 5
5 | ---
6 |
7 | Familiar with Docker, and looking for more specific information about when images get pulled or updated in Tugboat?
8 | Here's what you need to know about `docker pull` under the hood:
9 |
10 | - [When does Tugboat pull a Docker image?](#when-does-tugboat-pull-a-docker-image)
11 | - [When does Tugboat update a Docker image?](#when-does-tugboat-update-a-docker-image)
12 |
13 | ## When does Tugboat pull a Docker image?
14 |
15 | Tugboat doesn't pull the images in your config file every time you open a pull request, or refresh a Preview; it only
16 | does a `docker pull` (under the hood) when:
17 |
18 | - You [build a Preview](/building-a-preview/administer-previews/build-previews/) from scratch (without using a Base
19 | Preview)
20 | - You [Rebuild](/building-a-preview/administer-previews/change-or-update-previews/#rebuild-previews) a Preview that was
21 | not built from a Base Preview
22 |
23 | Otherwise, Tugboat relies on the images you pulled when the Preview was first created; Preview Actions like
24 | [Refreshing a Preview](/building-a-preview/administer-previews/change-or-update-previews/#refresh-previews),
25 | [Cloning a Preview](/building-a-preview/administer-previews/build-previews/#duplicate-a-preview), or
26 | [automatically generating a Preview from a pull request](/building-a-preview/automate-previews/auto-generate/) when
27 | you're using a Base Preview - those things all keep the Docker images you referenced when you first built the Preview.
28 |
29 | ## When does Tugboat update a Docker image?
30 |
31 | Because Tugboat pulls your Docker images at the beginning of the Preview build process, it won't `docker pull` an
32 | updated image unless you kick off the Preview build process from scratch again.
33 |
34 | For more info, see:
35 | [Why Build phases matter](/building-a-preview/preview-deep-dive/how-previews-work/#why-build-phases-matter).
36 |
37 | {{% notice tip %}} If your Tugboat Preview isn't pulling your latest Docker image tag, it might be because you're
38 | building from a Base Preview. If that's the case, you'll need to
39 | [Rebuild your Base Preview](/building-a-preview/work-with-base-previews/change-or-update/#change-a-base-preview), which
40 | executes an API call to `docker pull` under the hood to grab the image tag referenced in your
41 | [config file](/setting-up-tugboat/create-a-tugboat-config-file). If that still doesn't get you the image you expect,
42 | check your config file to see which [image tag](../image-version-tags/) you're pulling; you may need to change the
43 | reference to latest, or a specific image tag, to get the result you want. {{% /notice %}}
44 |
--------------------------------------------------------------------------------
/content/third-party-integrations/diffy-integration.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Diffy Integration"
3 | date: 2020-07-17T17:00:00-04:00
4 | weight: 10
5 | aliases:
6 | - /starter-configs/code-snippets/diffy-integration
7 | ---
8 |
9 | Tugboat does not provide `visualdiffs` for pages behind authentication. If you need to generate visual diffs from pages
10 | that are protected behind a login screen, you can set up [Diffy](https://diffy.website/) for your Tugboat Previews.
11 | Diffy is a third-party visual diffing tool.
12 |
13 | ## Prerequisites
14 |
15 | 1. You'll need to set up the project in Diffy, and get the numeric project ID from Diffy.
16 | 2. You'll need a Diffy API key to communicate with Diffy.
17 |
18 | ## Tugboat Repository Configuration
19 |
20 | Create Tugboat [environment variables](/setting-up-services/how-to-set-up-services/custom-environment-variables/) to
21 | store your `DIFFY_API_KEY` and `DIFFY_PROJECT_ID`:
22 |
23 | 
24 |
25 | ## Tugboat config.yml
26 |
27 | With the envvars configured in your Tugboat repository, use this snippet in your
28 | [configuration file](/setting-up-tugboat/create-a-tugboat-config-file/) to communicate with Diffy via a
29 | [service](/setting-up-services/) that has PHP installed.
30 |
31 | ```yaml
32 | services:
33 | apache:
34 | commands:
35 | init:
36 | # The Diffy CLI tool requires PHP. If the service image does not have PHP
37 | # installed, do it here
38 | #- apt-get update
39 | #- apt-get install php-cli
40 |
41 | # Download the Diffy CLI tool, and authenticate. The latest version can be
42 | # found at https://github.com/DiffyWebsite/diffy-cli/releases
43 | - curl -L https://github.com/DiffyWebsite/diffy-cli/releases/download/0.1.33/diffy.phar -o /usr/local/bin/diffy
44 | - chmod +x /usr/local/bin/diffy
45 | - diffy auth:login ${DIFFY_API_KEY}
46 |
47 | # Clean up after apt-get, if it was used
48 | #- apt-get clean
49 | #- rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
50 |
51 | online:
52 | # If you would like to compare this service with production
53 | - diffy project:compare ${DIFFY_PROJECT_ID} prod custom --env2Url="${TUGBOAT_SERVICE_URL}"
54 | --commit-sha=${TUGBOAT_PREVIEW_SHA}
55 |
56 | # If you would like to compare this service with its base preview
57 | - |
58 | if [[ -n "$TUGBOAT_BASE_PREVIEW_URL" ]]; then
59 | diffy project:compare $DIFFY_PROJECT_ID custom custom \
60 | --env1Url=$TUGBOAT_BASE_PREVIEW_URL \
61 | --env2Url=$TUGBOAT_SERVICE_URL \
62 | --commit-sha=${TUGBOAT_PREVIEW_SHA}
63 | fi
64 | ```
65 |
--------------------------------------------------------------------------------
/layouts/404.html:
--------------------------------------------------------------------------------
1 |
2 | {{- .Store.Set "relearnOutputFormat" "html" }}
3 |
4 |
5 | {{- partial "meta.html" . }}
6 | {{- $title := partial "title.gotmpl" (dict "page" . "fullyQualified" true "reverse" true) }}
7 | 404
22 |{{ T "title-404" }}
23 | 24 |
25 | # Ah, dang. We tried to look up that page but all we found was this Tub Goat.
26 | ___.
27 | // \\
28 | (( ''
29 | \\__,
30 | /6 (%)\,
31 | (__/:";,;\--____----_
32 | ;; :';,:';`;,';,;';`,`_
33 | ;:,;;';';,;':,';';,-Y\
34 | ;,;,;';';,;':;';'; Z/
35 | / ;,';';,;';,;';;'
36 | o8o / / |';/~~~~~\,oO8/(
37 | o8o8O ( K | | Oo8OOo8Oo
38 | Oo(""o8""""""""""""""""8oo""""""")
39 | `\`' `' /'
40 | \ /
41 | \ _ /
42 | `-. .----<(o)_--. .-'
43 | --------(_/------(_<_/--\_)-----------
44 |