Changing Atlassian Connect BaseURL: Our Guide so Far & Pitfalls

Confluence Development Confluence Cloud
1

Hi, we ran into a pitfall when changing the baseURL with Atlassian Connect.

So, here our guide & including the pitfall:

  1. Make your app available under the new base URL. The old base url must stay valid during the transition period, because the roll out takes time.
  2. Update the baseURL in our atlassian-connect.json
  3. Allow the old URL in the /install endpoint :
    Spring Connect: by adding it to atlassian.connect.allowed-base-urls' Node Express Connect: By adding it to allowedBaseUrls` in the config.json
  4. Double check that the app is available on the old and new baseURL
  5. Deploy the new version of the app
    Because the baseURL changed, this update will be queued for a marketplace review.
    So, it you have to wait for Atlassian. That is why you need to keep the old baseURL alive.
  6. After the approval, you have to wait for the rollout. (Edit: Approval got in, rollout is happening)
  7. At least our instances got updated without admin approval.
  8. The healthcheck URL needs updating. The only way to do that is asking via support as far as I know. So, this will take a some time until support answers and then you can provide the required update.
  9. Create a new release manually with new descriptor location. We updated our descriptor with the new baseURL and that created a new version. However, the descriptor location that is polled is still the old location that is planned to go offline. Therefore, double check that the latest markeplace release has the new descriptor location and create a new version manually otherwise.

Pitfalls we noticed:

  • Changing the baseURL requires a marketplace approval. This was not clear to us. It is documented here.
    It surprised us, because a baseURL is a minor version change otherwise and doesn’t require customer admin approval. So, because of that we didn’t expect that there will be a Marketplace review.
  • healthcheck URL is somewhere deeply burried in the Cloud Fortified program. You have to ask support.
  • Double check that the marketplace also scans the descriptor at the new location.

Generally: Take your time. Monitor the logs to see that no suprising traffic arrives at the old URLs.

7 Likes
2

We did something similar some months ago, I’ve written about our experience in this thread.

The hardest gotcha for us was that instance admins had to approve the update, meaning that the old system could not be switched off after ~48h hours as initially planned. Instead we waited for weeks and then wrote the last 2-3 remaining customers individual e-mails asking them to click the update button. Ugly thing.

All the best for your update!

3

Hmm. Our own instances of the app got updated without any admin approval.

Anyway: We’ll let the update sit for a week and then check how what URLs actually are in use in the wild. Then either give more time / pushing.

At some point customers on the ‘old’ descriptor will get a hard error telling them to update.

I’ll update this post on how this goes.

4

Out of curiosity: did your domain change or did the new version just move to a new path? I’d like to understand what triggered the admin approval with our update…

6

We moved to a new domain. We’ll monitor the progress. Seems the instances we control got migrated without any admin approval, as it is a ‘minor’ update.

However, we’ll have to wait for a bit to check what the customer’s installations will do.

7

Updates:

  • The healthcheck URL must be updated by Atlassian support.
  • Double check/update the descriptor URL in the marketplace.
    The marketplace picked up all new URLs from the updated descriptor. However, it doesn’t know that the descriptor itself also moved. So, you might have to update that as well.

Last Update: Migration complete. No more extra pitfalls noticed.

Anyway, updated the original post with these steps.