クラウド
Data Center と Server 8.1
バージョン

アドオンの更新方法

Bitbucket Server アップグレード ガイド

このページの内容

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

This document and referenced resources are here to help reduce the time and effort needed on your part to make your app compatible with Bitbucket 4.0.

Version numbering for Stash (3.x and earlier) has been left intact; for example, if you're running Stash 3.10.0, you can use app versions listed as compatible with Bitbucket Server 3.10.0.


変更について

Bitbucket Server 4.0 is the biggest API release Stash has ever seen. The decision to break so many apps with this release was not taken lightly. As developers, we understand the friction such changes can cause. However, we strongly believe this short term pain will be for long term gain with a clearer, cleaner, more consistent and more robust API in 4.0 and beyond. We are making quite a few large changes in this release in the interest of consistency, and with the strong hope that we will not need to make such a drastic change again anytime soon.

このページの内容

バックエンドの変更

One of the exciting changes with this release is the new JDK minimum requirement of 1.8, that allows you to use a wide new array of language features in your app code. While Stash 3.x supports running on Java 8; Bitbucket Server supports compiling to Java 8.

The largest change was we renamed our package namespace from com.atlassian.stash to com.atlassian.bitbucket, but this should also be a simple change when you update your plugins. The Bitbucket Server team updated over 100 apps internally and the process was quite straightforward using refactoring support in modern IDEs. 

再パッケージに加え、コードベースからすべての @deprecated API を削除しました。これらのほとんどには既存の置き換えメソッドが設定されていましたが、一部は置き換えられることなく削除されました。新しいメソッドが明確でない場合は最新の Stash 3.x ドキュメントで、使用すべき置き換えメソッドの詳細をご覧いただけます。

Finally, several of our bundled plugins were exporting API (our com.atlassian.stash:stash-build-integration plugin, for example), which meant plugin developers added dependencies on that jar. However, only a small portion of the code in that jar was exported. This was a frequent source of plugin issues because plugin developers attempted to use our internal classes. In 4.0, the exported APIs from all of our plugins have been extracted into separate modules (like with the stash-build-integration example, the build API is now in com.atlassian.bitbucket.server:bitbucket-build-api). These new API modules contain all of the code that is published for plugin developers to use.

フロントエンドの変更

Our Javascript and Soy API modules have moved to the Bitbucket namespace.  AMD Modules, previously found under stash/api/*, are now bitbucket/*. Non-API modules will be under bitbucket/internal.  For example, stash/api/util/navbuilder is now bitbucket/util/navbuilder.  For API Soy templates, these are now also under the bitbucket namespace - Stash.template.branchSelector is now bitbucket.component.branchSelector.

Another front-end change is that most keys – including Form Fragments, Web Panel & Section locations, and Web Resource apps – have been moved to Bitbucket namespaces. There is more detail on these changes below.

4.0 での削除を前提に非推奨となっていたメソッドやモジュールは削除されました。

How to update your app

The app key of your plugin must not change

The value of your app key, as defined within the atlassian-plugin.xml file, must not change. This is often defined in terms of the maven groupId and artefactId of your plugin. This value is used by Atlassian Marketplace and other parts of Bitbucket Server as a unique identifier for your plugin. Changing this value could lead to data loss, and will cause you to lose review and download history on the Atlassian Marketplace.

たとえば、pom.xml で、以下の変数の値を、groupId と artifactId の値に置き換えます。 

<atlassian-plugin key="${project.groupId}.${project.artifactId}" ...


  1. Bitbucket Server 4.0 の最新バージョンを参照するように pom.xml を更新します。Bitbucket Server と AMPS の両方のバージョン プロパティを更新する必要があります。これには現在、Bitbucket Server プラグインをビルドするためのプレリリース バージョンと、任意の API アーティファクトへの依存関係が必要となります。

    <dependency>
    <groupId>com.atlassian.bitbucket.server</groupId>
    <artifactId>bitbucket-api</artifactId>
    <version>${bitbucket.version}</version>
    <scope>provided</scope>
</dependency>
...
<properties>
   <bitbucket.version>4.0.0</bitbucket.version>
   <bitbucket.data.version>${bitbucket.version}</bitbucket.data.version>
   <amps.version>6.1.0</amps.version>
   ...
</properties>

  2. In your pom.xml you will also need to change or add configuration for the bitbucket-maven-plugin (depending on whether you are supporting both Stash and Bitbucket Server, or just Bitbucket Server):

    <build>
    <plugins>
        <plugin>
            <groupId>com.atlassian.maven.plugins</groupId>
            <artifactId>bitbucket-maven-plugin</artifactId>
            <version>${amps.version}</version>
            <extensions>true</extensions>
            <configuration>
                <products>
                    <product>
                        <id>bitbucket</id>
                        <instanceId>bitbucket</instanceId>
                        <version>${bitbucket.version}</version>
                        <dataVersion>${bitbucket.data.version}</dataVersion>
                    </product>
                </products>
            </configuration>
        </plugin>
    </plugins>
</build>

  3. Update your app name and description in pom.xml to reference "Bitbucket" instead of "Stash". For example:

    <name>Bitbucket Server - Realtime Editor</name>
<description>Provides support for real-time collaborative editing.</description>

  4. オプション: プラグインが Bitbucket Server のみをサポートする場合は、Stash の依存関係を削除します。

    <groupId>com.atlassian.stash</groupId>
<artifactId>stash-api</artifactId>
  5. For a class with compilation errors, first remove any com.atlassian.stash import statements that are red.
  6. IDE が提供するインポート候補を使用し、API の変更履歴と以下の表を確認します。
  7. Open the atlassian-plugin.xml inside your IDE
    1. Rename any com.atlassian.stash imported components to com.atlassian.bitbucket (or equivalent as mentioned in the API changelog)
    2. If you are using any web-resources with a dependency on com.atlassian.stash.stash-web-api, change them to com.atlassian.bitbucket.server.bitbucket-web-api
    3. フロントエンド API の名前の変更によって必要となる、リソース内の他の変更を確認します

  8. If your app has JavaScript which uses the Stash JavaScript API, change your AMD module imports from stash/api/* to bitbucket/*

  9. Test the app starts in Bitbucket Server using:

    mvn clean bitbucket:debug

その他の便利なリソース

API の変更の概要

Java パッケージ

Stash 3.x
com.atlassian.stash

Bitbucket 4.x
com.atlassian.bitbucket

App Key (in atlassian-plugin.xml)

Stash 3.x

<atlassian-plugin key="${project.groupId}.${project.artifactId}" ...>

または

<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>


Bitbucket 4.x

<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>

(いずれの場合も変更しないでください)

<atlassian-plugin key="com.myorg.stash.awesome-plugin" ...>


Maven プラグイン

Stash 3.x

<artifactId>maven-stash-plugin</artifactId>
例:
<plugin>
 <groupId>com.atlassian.maven.plugins</groupId>
 <artifactId>maven-stash-plugin</artifactId>
 <version>${amps.version}</version>
 <extensions>true</extensions>
 <configuration>
   <products>
    <product>
     <id>stash</id>
     <instanceId>stash</instanceId>
     <version>${stash.version}</version>
     <dataVersion>${stash.data.version}</dataVersion>
    </product>  
   </products>
  </configuration>
</plugin>


Bitbucket 4.x

<artifactId>bitbucket-maven-plugin</artifactId>
例:
<plugin>
 <groupId>com.atlassian.maven.plugins</groupId>
 <artifactId>bitbucket-maven-plugin</artifactId>
 <version>6.1.0</version>
 <extensions>true</extensions>
 <configuration>
  <products>
   <product>
    <id>bitbucket</id>
    <instanceId>bitbucket</instanceId>
    <version>${bitbucket.version}</version>
    <dataVersion>${bitbucket.version}</dataVersion>
   </product>  
  </products>
 </configuration>
</plugin>


例外

Stash 3.x

com.atlassian.stash.exception.ServiceException 

Bitbucket 4.x

com.atlassian.bitbucket.ServiceException

The monolithic com.atlassian.stash.exception package has been removed. The exceptions it previously contained have been moved into the module they belong to. For example, NoSuchRepositoryException is now in the com.atlassian.bitbucket.repository package.

Java User モデル

Stash 3.x

com.atlassian.stash.user.StashUser 

Bitbucket 4.x

com.atlassian.bitbucket.user.ApplicationUser

Java Authentication Context

Stash 3.x

com.atlassian.stash.user.StashAuthenticationContext

Bitbucket 4.x

com.atlassian.bitbucket.auth.AuthenticationContext

Java Event モデル

Stash 3.x

com.atlassian.stash.event.StashEvent

Bitbucket 4.x

com.atlassian.bitbucket.event.ApplicationEvent

The monolithic com.atlassian.stash.event package has been broken down and the events it formerly contained have been moved into subpackages. For example, RepositoryCreatedEvent is now in com.atlassian.bitbucket.event.repository

Java モデル

Stash 3.x

Changeset, DetailedChangeset

Bitbucket 4.x

Commit, Changeset

命名規則を標準化しました。

  • "commit" は、リポジトリのコンテンツが変更されたイベントです
  • "changeset" は、2 つのコミット間に存在する変更のセットです
  • コードベースは "changeset" と "commit" という単語を互換的に使用しなくなりました。それぞれの単語は固有の概念を表します。

All classes and interfaces with Changeset in the name have replaced with an equivalent class or interface with Commit in the name instead.

What was formerly a DetailedChangeset, because the object that should have been called a Commit had already stolen the Changeset name, is now called a Changeset

Java Pull Request Participant モデル

Stash 3.x

PullRequestParticipantSearchRequest

PullRequestParticipantSearchCriteria

Bitbucket 4.x

PullRequestParticipantRequest

PullRequestParticipantCriteria

Soy テンプレート

Stash 3.x

チェンジセット

Bitbucket 4.x

commit

アプリケーションの定数

Stash 3.x

com.atlassian.stash.Product

  • #NAME="Stash"
  • #DATA_CENTER_NAME="Stash Data Center"
  • #FULL_NAME="Atlassian Stash"

Bitbucket 4.x

com.atlassian.bitbucket.Product

  • #NAME="Bitbucket"
  • #DATA_CENTER_NAME="Bitbucket Data Center"
  • #FULL_NAME="Atlassian Bitbucket"

ライセンスの変更

Stash 3.x

com.atlassian.extras.api.stash.StashLicense

Bitbucket 4.x

com.atlassian.extras.api.bitbucket.BitbucketServerLicense

POM に次の依存関係を追加します。

<dependency>
     <groupId>com.atlassian.extras</groupId>
     <artifactId>atlassian-extras-api</artifactId>
     <scope>provided</scope>
</dependency>


Javascript API モジュール

Stash 3.x

stash/api/* (eg. stash/api/util/server)

Bitbucket 4.x

bitbucket/* (eg. bitbucket/util/server)

Soy API の名前空間

Stash 3.x

stash.template.branchSelector

Bitbucket 4.x

bitbucket.component.branchSelector

Web API プラグイン モジュール

Stash 3.x

com.atlassian.stash.stash-web-api

Bitbucket 4.x

com.atlassian.bitbucket.server.bitbucket-web-api

ここまでで多数の API リソースを追加済みのため、web リソースの依存関係をより表現することができます。これらのリソースの詳細については、Web UI API の更新済みのドキュメントをご確認ください。

Core web プラグイン モジュール

Stash 3.x

com.atlassian.stash.stash-web-plugin

Bitbucket 4.x

core プラグインには内部モジュールのみが含まれます。このプラグインをほかのプラグインで参照することはできません。

Web パネルとセクションの場所

Stash 3.x

stash.*

e.g. stash.branch.list.actions.dropdown

Bitbucket 4.x

bitbucket.*

e.g. bitbucket.branch.list.actions.dropdown

Web リソースのコンテキスト

Stash 3.x

stash.*

e.g. stash.layout.pullRequest

Bitbucket 4.x

bitbucket.* 

bitbucket.layout.pullRequest

プラグインのデコレーター

Stash 3.x

stash.*
e.g. stash.repository.settings

Bitbucket 4.x

bitbucket.* 

bitbucket.repository.settings

プラグインのデコレーターのドキュメントを参照

Web リソースのモジュール

Stash 3.x

<stash-resource/>

Bitbucket 4.x

<client-resource/>

Note that client-resource will expand <directory/> elements in-place, where stash-resource expanded them at the end.

Web アイテムのアイコン (atlassian-plugin.xml 内)

Stash 3.x

<param name="stashIconClass">...</param>

Bitbucket 4.x

<param name="iconClass">...</param>

Web の国際化

Stash 3.x

stash_i18n

Bitbucket 4.x

getText、getTextAsHtml

stash_i18n should not be used; getText is a cross-product replacement that doesn't accept a default translation parameter. See Writing Soy Templates for usage details. Note that these templates for Confluence work for Bitbucket too.

フォームのフラグメント

Stash 3.x

stash.*

Bitbucket 4.x

bitbucket.*

JavaScript イベント

Stash 3.x

stash.*

Bitbucket 4.x

bitbucket.internal.*

JavaScript イベントの追加情報については以降をご確認ください。

国際化のキー

Stash 3.x

stash.*

Bitbucket 4.x

bitbucket.*

Java API - Guava

Stash 3.x

com.google.common.base.Function/Predicate

プラグインで Guava 11 を利用できました。

Bitbucket 4.x

Java 8 Lambdas

Function や Predicate などの Guava タイプは API タイプ署名では使用されなくなりました。java.util.function の対応するタイプを使用してください。

プラグインで Guava 18 を利用できます

サーブレットの依存関係

Stash 3.x

<groupId>javax.servlet</groupId>
    <artifactId>servlet-api</artifactId>
    <scope>provided</scope>
</dependency>

Bitbucket 4.x

<groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <scope>provided</scope>
</dependency>

artifactId は servlet-api から javax.servlet-api に変更されました。

ブランチの権限

Stash 3.x

canDelete、canWrite
検索

Bitbucket 4.x

hasPermission

Checking for access to a Ref is now done by calling the RefRestrictionService's hasPermission method.

The search method for AccessGrants has been removed. AccessGrants can now be accessed by calling getAccessGrants on a RefRestriction.

エクスポートされたサードパーティ ライブラリ

Stash 3.x

Apache HTTP Client 3.x はホスト アプリによってエクスポートされなくなりました。

Bitbucket 4.x

代わりに HTTP Client 4.x を使用します。

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <scope>provided</scope>
</dependency>


SAL Scheduler の非推奨

Stash 3.x

SAL 2.0

com.atlassian.sal.api.scheduling.PluginScheduler

(Bitbucket 4.0.0 は scheduleJob に渡されたジョブが

java.io.Serializable を実装しない場合、IllegalArgumentException を返すため)

Bitbucket 4.x

SAL 3.0 (see SAL 3.0 upgrade guide for further details)

Use com.atlassian.scheduler.SchedulerService provided by:

<groupId>com.atlassian.scheduler</groupId>
<artifactId>atlassian-scheduler</artifactId>

を使用します。

REST API への変更の概要

The payloads for some of the REST resources have changed. All URLs are the same except that the default context path is now /bitbucket instead of /stash.

Some REST model classes, like RestStashUser, had their "self" links defined two ways:

  "link": {
    "url": "/users/admin",
    "rel": "self"
  },
  "links": {
    "self": [
      {
        "href": "http://localhost:7990/stash/users/admin"
      }
    ]
  }

The "link" attribute is from 1.0 and was deprecated in 2.11. From 4.0, the "link" attribute has been removed. The "self" entry in the "links" map remains.

Changeset to Commit

Ref output, such as branches and tags, had a "latestChangeset" attribute. The following output is from the /projects/KEY/repos/slug/branches resource:

{
  "size": 1,
  "limit": 1,
  "isLastPage": false,
  "values": [
    {
      "id": "refs/heads/search/STASHDEV-8813-search",
      "displayId": "search/STASHDEV-8813-search",
      "latestChangeset": "de307ea7b6abfa1aad8de6771d79da0a9a7fd3cb",
      "latestCommit": "de307ea7b6abfa1aad8de6771d79da0a9a7fd3cb",
      "isDefault": false
    }
  ],
  "start": 0,
  "nextPageStart": 1
}

A "latestCommit" attribute was added in 3.7 and "latestChangeset" was deprecated. It has been removed in 4.0. This also applies to pull request refs.

AttributeMap to PropertyMap

Some REST objects, most notably RestPullRequest, had an "attributes" attribute which allowed plugin developers to attach arbitrary data. However, the model for this was very restrictive, being defined in AttributeMap as Map<String, Set<String>>. In 3.2, PropertyMap, defined as Map<String, Object>, was added to replace the attribute support. However, for performance and API consistency reasons, most existing attributes were not converted over. In 4.0, the changeover is now complete.

次の JSON スニペットは、プル リクエストのプロパティの古いレイアウトと新しいレイアウトを表示します。

Stash 
  "attributes": {
    "resolvedTaskCount": [
      "0"
    ],
    "openTaskCount": [
      "1"
    ],
    "commentCount": [
      "2"
    ]
  }
Bitbucket Server 
  "properties": {
    "commentCount": 2,
    "openTaskCount": 1,
    "resolvedTaskCount": 0
  }

As you can see, the new "properties" map allows its numeric entries to be numeric, resulting in much more readable, useful output.

PullRequestOrder default order

The getDefaultOrderForState(PullRequestState state) method in PullRequestOrder has been replaced with
getDefaultOrder(), which always returns PullRequestOrder.NEWEST.

XSRF 保護を既定で有効化

悪意のあるユーザーが外部のサイトから Stash インスタンスにフォームを送信することを防ぐため、すべての REST リソースで XSRF 保護が既定で有効化されるようになりました。これは "application/json" Content-Type を許可しません。 

これらのリソースに POST するすべてのクライアントは、この確認を無効化するために特別なヘッダーを追加する必要があります。

ヘッダー名: X-Atlassian-Token

ヘッダー値: no-check

たとえば、curl 経由でプロジェクトのアバターを設定したい場合、次のコマンドを使用できます。

$ curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://localhost:8080/rest/api/1.0/projects/TEST/avatar.png -F avatar=@avatar.png 
-H "X-Atlassian-Token: no-check" パラメーターは 3.x では不要でしたが、4.0 以降では必要になりました。


"application/json" を許可しない (例: multipart/form-data、plain/text) 自身の REST リソースでは、@XsrfProtectionExcluded アノテーションを使用して XSRF 保護からオプトアウトできます。

除外されたアノテーションを使用している場合、XSRF/CSRF 攻撃への他のタイプの保護がエンドポイントで行われている可能性が考えられます。

JavaScript イベント

Since Stash 3.0 we have provided a Javascript API module for creating and consuming events (stash/api/util/events, now bitbucket/util/events), however we haven't documented what events Bitbucket (Stash) emits as part of our Developer Docs. Which events should be used and which should be considered internal implementation details were subject to change.  

We are actively looking at which events we should consider part of the API. We will document usage and guarantee the stability for events that are part of the API for a major version. We would like to hear any feedback on which events you make use of in your apps, and why, to aid in our consideration of what to consider for the JS Events API.

App update strategies

There are two primary strategies we are suggesting to update your app, and here we explain how to implement each and how to provide support for your app going forward.

互換性なし

The simplest way forward is to branch your app and only release Bitbucket Server 4.0 compatible versions in the future. Replace the old com.atlassian.stash dependency with the new com.atlassian.bitbucket one, fix the resulting compilation errors, and create a new listing on Marketplace.

前方/後方互換性

これを実現する最適な方法は、プラグインの "Stash" バージョンのブランチを保持し、"Bitbucket Server" バージョンを含む master ブランチに変更をマージすることです。

Unfortunately, unless you have written a pure cross-product app, building two versions from the same branch of code is in general not worth the overhead.

チェックリストの名前変更

  1. Beware of changing any Strings which are used as keys for accessing data your app may store. e.g. namespaces used with PluginSettingsFactory.createSettingsForKey or prefixes used with ApplicationPropertyService.getPluginProperty
  2. We strongly recommend that you do not change your app key; if you do, customers won't be able to see the updated version of your app in their Universal Plugin Manager. The default atlassian-plugin.xml generated by AMPS uses  key="${project.groupId}.${project.artifactId}". Changing your Maven groupId or artifactId this will change your app key.

  3. If you are using ActiveObjects, you are strongly encouraged to set the namespace attribute to ensure the unique hash in your table names does not change. Otherwise anyone who has installed your plugin will "lose" all of their data when your plugin starts using new tables!
    For example, here's how we defined the <ao/> module in our ref sync plugin: 

    <ao key="ao" namespace="com.atlassian.stash.stash-repository-ref-sync">
最終更新日 2022 年 11 月 8 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.