Managing Integrations

Integrations let you store secrets securely and use them during your CI and Assembly Line workflows. These secrets could be passwords, keys, tokens, key-value pairs, etc, and can be used to connect your workflows with third-party services or just to store sensitive information that shouldn't be exposed. A list of supported integrations is available in our Integrations overview document.

While creating an integration, you are asked to give it a friendly name which can then be referenced as needed in the YAML configuration file shippable.yml.

Creating an integration

You can create an integration in one of two ways:

  • Org integrations (recommended for teams): These are integrations that are created at a Subscription level, and can be scoped to be used by a subset (or all) of repositories within that Subscription. Access to these integrations is controlled based on Admin, Member, and Collaborator roles. A user that has access to an org integration also has permissions to view and update it in the Shippable UI.

  • Account integrations: These are integrations that are created at an Account level, and can be scoped to be used by repositories across several Subscriptions. Only the user who creates an Account integration is allowed to view integration details or update it.

  • Go to your Subscription integrations dashboard by selecting your Subscription from the left navigation bar, clicking on the Gear icon at the top right of your Subscription dashboard, and selecting Integrations.

  • To add a new integration, click on the + icon in the top right corner.

Subscription integrations

  • Select the Create a subscription integration tab.

  • Give your integration a friendly name and select the type of integration you want to create. Please note that the friendly name specified here should be used in your CI and Assembly Lines config.

Subscription integrations

  • Complete all integration-specific fields. For instructions, go to the Integrations overview doc and select the specific third-party integration you're configuring.

  • For the Edit Permissions dropdown, choose the Roles that can update this integration. For an explanation of how your Source Control Provider organization/team roles map to Shippable roles, please read our roles and permissions doc. If a user's role is allowed access to this integration, they can view integration details and modify the integration.

  • Select the repositories that can use this integration. This means that any shippable.yml files in these repositories can reference this integration. Default is All projects.

  • Click on Save.

Creating an account integration

  • From the left navigation bar, click on Integrations. This will take you to your Account integrations dashboard, which shows all the account integrations you've created.

Account integrations

  • Click on + icon at the top right.

  • Give your integration a friendly name.

  • Choose the right Integration type, depending on what you're trying to configure. Complete all integration-specific fields and click on Save. For instructions on how to complete the fields for a specific integration, go to the Integrations overview doc and select the specific third-party integration you're configuring.

Account integrations

  • Please note that while creating the integration, you will need to specify which Subscriptions and/or Projects have access to it.

You can also create an account integration by going to your Subscription integrations dashboard, clicking on + to add an integration, selecting the Use an account integration tab, and creating an integration.

Viewing integrations

You can view a list integrations at the following places:

Subscription integrations dashboard

Your Subscription integrations dashboard shows you a list of integrations are available to that specific Subscription. Subscription integrations can be org integrations, or account integrations that were scoped to include that Subscription.

To view Subscription integrations:

  • Select your Subscription from the left navigation bar.

Subscription integrations

  • Click on the Gear icon in the top right menu, and select Integrations

Subscription integrations

  • You will see a list of your Subscription integrations. Shared and account integrations are distinguished by icons as shown below:

Subscription integrations

Account integrations dashboard

Account integrations dashboard shows you a list of your account integrations.

  • From the left navigation bar, click on Integrations.

Account integrations

Clicking on any individual integration will show you details for that integration.

Updating integrations

You can update org integrations by going to the specific Subscription integration dashboard, and account integrations from the Account integration dashboard.

Updating org integrations

  • Go to your Subscription integrations dashboard by selecting your Subscription from the left navigation bar, clicking on the Gear icon at the top right of your Subscription dashboard, and selecting Integrations.

  • Click on the integration you want to update to go to the Edit page. Here, you can update any field that you have permissions to.

  • Make the updates and click on Save.

Updating account integrations

  • From the left navigation bar, click on Integrations. This will take you to your Account integrations dashboard, which shows all the account integrations you've created.

  • Click on the integration you want to update to go to the Edit page.

  • Make your updates and click on Save.

Updating a Subscription integration created from an account integration

If you have a Subscription integration that was created as a result of an account integration being scoped to include that Subscription, you can change it to point to another account integration if needed.

This is very useful in scenarios where an employee creates an account integration and uses it in CI/Assembly Line workflows for your organization, and then leaves the company or somehow loses access to the organization. To avoid a situation where you need to create a new integration and update your YAML config everywhere, we let you point the same Subscription integration to a different account integration.

Please note that this functionality is only available for Subscription Admins.

To do this:

  • Go to your Subscription integrations dashboard by selecting your Subscription from the left navigation bar, clicking on the Gear icon at the top right of your Subscription dashboard, and selecting Integrations.

  • Click on the integration you want to update to go to the Edit page. Here, you can update the following:

    • Integration name, which is used to reference this integration in your YAML config for CI and Assembly Lines
    • Associated personal (i.e. Account) integration. This is a great way to update your secrets without needing to touch YAML config.
  • Make your updates and click on Save.

Deleting integrations

Depending on the type of integration, instructions to delete are given below.

Deleting org integrations

  • Go to your Subscription integrations dashboard by selecting your Subscription from the left navigation bar, clicking on the Gear icon at the top right of your Subscription dashboard, and selecting Integrations.

  • Click on the integration you want to delete. On the Integration Edit page, click on Delete in the Delete Integration panel.

Please note that if this integration is being used in any resources or jobs that are in your CI or Assembly Line workflows, you will see a list of these instead of the Delete button. Remove the integration from the jobs and resources, and then delete the integration.

Deleting account integrations

  • Go to your Subscription integrations dashboard by selecting your Subscription from the left navigation bar, clicking on the Gear icon at the top right of your Subscription dashboard, and selecting Integrations.

  • Click on the integration you want to delete. On the Integration Edit page, click on Delete in the Delete Integration panel.

Please note that if this integration is being used in any resources or jobs that are in your CI or Assembly Line workflows, you will see a list of these instead of the Delete button. Remove the integration from the jobs and resources, and then delete the integration.

Deleting Subscription integration created from an account integration

If you delete a Subscription integration that was created as a result of an account integration being scoped to include that Subscription, deleting it just alters the account integration scope to exclude that Subscription. It does not actually delete the account integration from the account of the person who created it.