Skip to end of metadata
Go to start of metadata

You can use Bitbucket to host a static website. A static website contains coded HTML pages with fixed content. Websites hosted in this way have the domain in their URL, for example,  Another example, is the site maintained by the Bitbucket 101 tutorial that lists favorite quotes by Bitbuckians.  

Publishing a static website on Bitbucket requires you to combine your account's name with the domain suffix. So, your account's name must be acceptable to your DNS service. Upper case characters and special characters are typically not acceptable. For example, if your account's name is happy_cat, you would need to create a new account with a username of happycat to use this feature because underscores are not allowed in DNS hostnames. Your repository name would be and the published static website is reached by this URL:

The following topics appear on this page: 

Configure a Website for Hosting

To use this feature, do the following:

  1. Log into your Bitbucket account.
  2. Create a repository and making sure to Name it using the following format:

    The repository name needs to include the trailing For example, if your accountname is tutorials (1) your repository Name should be this (2)
  3. Clone your repository to your local system.
  4. Create  an index.html file in the repository root.
    Keep in mind the names are case sensitive; Bitbucket treats index.html and Index.html as different file names. Make sure your file is named index.html – all lowercase.
  5. Add index.html file to your repository, commit the change, and push the result to Bitbucket.
  6. Navigate to the site.
    For example, if your username is is tutorials you would navigate to The system displays the HTML in the site's index.html.  

Technical Features and Limitations of this Feature

Static websites on Bitbucket support the following features:

  • Embedding images and other media. 
  • Inclusion of JavaScripts in your HTML pages.
  • Blog comments by embedding Disqus in your site.

This feature turns a repository into a plain static webserver that uses the repository's root as the web root. Bitbucket does not support the use of HTTPS with this feature; you cannot log into the site. The system does not issue cookies for these domains. Server-side scripts or code are not supported. You cannot use PHP or other server-side scripting languages on the site.

Finally, Atlassian injects a rum.js script into each Bitbucket website. This script captures internal web analytics and statistics.

Hosting Multiple Projects Under a Single Website

You may have multiple projects that you want to host from the same Bitbucket websites, you can do this by placing each project in a repository subdirectory. In this example, you would want to organize things such that you can point users to:


Each project sub-directory would act as a self-contained website with its own index.html.

Bitbucket is forgiving with regard to trailing slashes: a request to with result in projectX/index.html being served (if such a file exists), regardless of whether the trailing slash is included in the URL.

Public and Private Repositories and Static Websites

The static website you create with this feature is just like any other website on the Internet — anyone with the URL (address) can visit and view your static website.  The underlying Bitbucket repository can be a public repository or a private repository.  This means if your Bitbucket repository is private, users can still visit and view the static website.  The same is true if the underlying repository is public.


  1. Anonymous

    What an absolutely superb facility! I was looking around for some static hosting for some technical articles after my regular ISP was complaining after one got a flurry of interest and blew my months bandwidth quota in a few hours, but couldn't find anything which didn't want to treat me like an idiot.  I already use bitbucket for source control, and this'll let me bring supporting website materials into the same fold.  And using hg to update the live version of the site is just so much nicer than messing around with FTP on my ISP's pages.  Nice!

  2. Anonymous

    What a very clear documentation about this topic ! Just like every Atlassian's docs. Congrats guys that's what good job is ^^

  3. Anonymous

    Awesome! One question though: this doesn't seem to work with submodules, am I mistaken? Will this be added as a feature, or could I create a ticket somewhere?


    1. I'm not sure I understand what you mean by "submodules" – you can create sub projects.  You can create a ticket at the Bitbucket issue tracker.

    2. Anonymous

      Also would like to know an answer on this question..


      Maybe Erik van Zijst [Atlassian] can help us?

  4. Does Bitbucket pages supports hosting and serving SWF files (using embed tag or swfobject) ?

    1. Ok not really reactive...

      I have tested and Bitbucket pages cannot be used to display SWF files embeded in an HTML wrapper.

      I have create an issue here :

  5. Maybe it is a good idea to check the user names being created against a forbidden names list.
    I chose the user name "cdn". Created a repo for a static website. And I just wasted 12+ hours trying to find out why I got the infamous "Access Denied" XML message from AWS on Until I found out that was already taken. No points for guessing by whom. (smile)
    I'm going to delete the repo and profile and give it another crack.

  6. Is posible configure a Octopress site in Bitbucket?. I have a tumblr blog (with Octopress theme) and need to migrate to an static website. In github is posible, but never works for me...

    Many thanks.

    1. We don't explicitly support it or not.  You'd have to try it.  The limitations on this page cover the known limitations; we don't support Disqus comments on blogs

    2. Anonymous

      Because octopress generates static websites as a final result, yes, this sounds like it would work fine (although I have not tried it).  

      IIRC, OP uses a rake file to automate some of the deployment steps, which my not configure the branch names correctly though, so the correct question would be, does octopress support bitbucket.  That being said, simply committing the final results so they work with bitbucket, sounds like it should work fine.

  7. Can a private repo be hosted on as a static website, and require HTTP auth and only allow viewers with credentials

      1. This question of pages of private repositories also be restricted to members of the project would be a great implementation. It would not require an authentication system on the page, but just the fact bitbucket be logged in and have permission already in the repository would be an interesting way to have private content across pages where the team could interact in some way.

  8. Thanks! 

    Any plans on adding such a feature? maybe as a paid plan?

  9. As Bitbucket users, do we have access to rum.js analytics results (e.g dashboard or something else) ? Thanks

    1. rum.js is used by our internal monitoring only and cannot be made available externally.

  10. If PHP is not allowed, does that mean a contact form would not work?

    1. Hi Justin, if it is written in PHP it wouldn't.  There is nothing that precludes you from trying.

  11. Anonymous

    Are there any restrictions about usage when hosting a site through bitbucket?

    1. Well, there are limitations as you see from the page.  I'm not sure what you mean by usage – that is a broad area.  If you can provide a bit of detail here or by sending an email to that would help.

      1. Anonymous

        When I say usage, I am referring to bandwidth and request/month

        1. Okay.  See this FAQ: What kind of limits do you have on repository/file/upload size?  Other than what is discussed here, we don't have limits or restrictions.

  12. FYI - issue #3856 appears fixed, although the bug is still in the "new" status. This means the paragraph beginning:

    If the trailing slash were omitted from the URL, this link would resolve to ...

    through the workaround are no longer relevant.


    I've confirmed that relative HREFs work regardless of whether the link into that directory had a trailing slash.  This is because the nginx server now replies with a 301 MOVED PERMANENTLY when redirecting with the trailing slash:

    $ curl -v
    * About to connect() to port 80 (#0)
    * Trying
    * connected
    * Connected to ( port 80 (#0)
    > GET /test-redirect HTTP/1.1
    > User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8x zlib/1.2.5
    > Host:
    > Accept: */*
    < Server: nginx/1.2.4
    < Date: Thu, 13 Jun 2013 17:32:49 GMT
    < Content-Type: text/html; charset=utf-8
    < Content-Length: 0
    < X-Request-Count: 400
    < X-Served-By: bitbucket16
    < X-Render-Time: 0.0528440475464
    < Content-Language: en
    < Vary: Accept-Language, Cookie
    < X-Version: c61135ea5149
    < ETag: "d41d8cd98f00b204e9800998ecf8427e"
    < Location:
    < X-Static-Version: c61135ea5149
    < Strict-Transport-Security: max-age=2592000
    < X-Content-Type-Options: nosniff
    * Connection #0 to host left intact
    * Closing connection #0


    1. This is fixed now! (smile) I've removed the workaround text.

  13. Hello, I followed the instructions but still got a 404 error. The repository is public and the index.html got content. I'm missing something or just have to wait some more minutes/hours? Thanks

    1. Berto,

      Is your repository name actually set to see an example here:


  14. Hi,

    Im getting this message while using my own CNAME pointing to my  repository:

    You were never here

    This user has requested we keep their identity a mystery. Let's never speak of this again.


    The repository is private , but i thought it didn't matter for your static website if private or public.

    Theres a index.html file in the root and just css, js files.


    any ideas?? or is it a DNS propogation waiting perios 24/48 hours??

    1. It sounds like you aren't going to a website but rather a repository.  What is your website?

      1. hi,

        my site is,

        The CNAME setup page shows a green tick and says it resolves ok to bitbucket

        The IP is:

        1. This won't work as a site served from Bitbucket. Your website name would need in the site name.  Maybe there is a misunderstanding.  What is the name of the bitbucket repository where your website resides?

          1. The website repository of the website is at:

            I've used the documentation to do this, the problem is that there's only an explanation of how to create the CNAME itself but not how to upload a site when this option is chosen.

            I used the information in the docs for creating a static website using <username> but used CNAME instead since theres no help (as stated in other threads) for how to use a  CNAME to point to a static website on bitbucket.

            I dare say using the method is easier but the CNAME op was exactly what i wanted. The CNAME option needs removing from the docs or a clear explanation of this option needs adding to the docs. I agree with other threads who have pointed out how sketchy this option is.

            1. Bitbucket can only serve a website when the site's URL is  So, in your case it would need to be  The purpose of  CNAME is to take an existing domain and resolve it to another domain.  So, for example, if you had the domain name you could set up your hosting service such that the hosting service forwarded visitors to  Each hosting service has its own means for setting up CNAMEs. I can't document that here, you need to visit your hosting service's documentation.

              You can an also point an existing domain to your Bitbucket account URL.  For that see this page: Associate an existing domain with an account.

              1. Ok, thanks for that - thats cleared up that confusion and my site is now finally working with with these changes. I took the point 'must resolve to bitbucket' literally to mean the site itself rather than a website/repository.  It might be clearer to some more than others who are more used to working with GIT, so you could add your excellent, clear explanation given in the last response to the documentation for people like me, use-to CNAME but new to GIT & GIT websites repo's.


                Though i'm still not sure how this associates an existing domain name with a bitbucket account?? if people get to this website using, then how is that associated with my own domain name with my web host?? - the way i wanted things working was to use the CNAME i created with my host to be the URL people use to get to my repo website on bitbucket?

                thank you.

                1. Anilee, I've updated the documentation. We've had a lot of fingers in this page and content has gotten munged over time.  You can setup a CNAME for your account .  You cannot set up a CNAME for a static website hosted on Bitbucket.  The account you setup a CNAME for may have a repository that represents a static website.

                  1. thanks MAnthony, got it now -

                    BTW: on the subject of Hosting Multiple Projects Under a Single Website, is there a way to create repository-subfolders on bitbucket or do we have to create the folder hierarchy on our machine then push the whole thing up to bit bucket?

                    1. Anilee,

                      You'd need to create the folder hierarchy locally and push it up to Bitbucket.

                      BTW, thank you for all your comments. They really gave me some good perspective in improving them.  (I'll be deleting the thread at some future date just to keep down on comment noise.)


                      1. thanks Mary,

                        this is exactly why i chose bitbucket over the others, as much as i liked the look of Source-forge/SVN and gitHub they don't seem as user friendly for DVCS noobs. Your response times and receptiveness to (constructive) issues from what ive experienced are 1st class.

                        thanks again,

                        anilee, UK

  15. Anonymous

    Is this feature supported on Stash? Is there documentation for it?

  16. I'm looking for a way to create private websites that are repository-specific and that require the same permissions to access as the repo requires. Basically I want to create a documentation website for each repository but I want full control over the page because I'm using the Apigen code generator for part of the site and it's pages are not embeddable into BitBucket like markdown pages.

    Is this possible with BitBucket?

    1. Mike, we don't support what you need.  All our websites support is on the account level, not the repository level. The best solution for you would be our Wiki's but as you point out, you can't embed an HTML page into Markdown. 

      1. Thanks for the quick reply manthony. Hopefully you can take this as a feature request, if nothing more than to be on par with GitHub?

        1. Mike, there is an outstanding request to provide this feature.  Please vote and watch it.  The team does look at votes when prioritizing features. 

          1. Thanks manthony - I upvoted. And it looks like a Top 10 feature request too.  I hope the "well into 2014 before considering" gets changed.

  17. Anonymous

    Is there a way to get Source Tree to just sync files like in Git-hub for Windows instead of having to push and pull after editing web pages.

    1. You should ask this question on

  18. Can I use a facebook ( comments, like, share ) on a static bitbucket website?!

    1. You can try and see if it works. 

    2. It's really just static hosting, so you can do anything you like, really. The only limitation is that you cannot make authenticated requests to Bitbucket.

      1. Erik is here, Erik  is there, Erik everywhere. (smile)

        I think about authentication you're right. (wink) 

  19. Since output from rum.js is not available for the user's reference, are there any other analytics or statistics tools we can use?

  20. Hi,

    Is It possible to have some private content? 
    Is Repository information like repository list accessible through ajax? 
    Will be possible to create a custom Repository list page?


  21. Anonymous

    Amazing Altassian .. Awesome as always.. It would be great if some resources could be secured with bitbucket login (authentication limited to bitbucket's default login mechanism) .. I know this is already better than I expected but you know I am always greedy (wink) 

  22. R H

    Hmm, if cookies do not work, then could a jquery cookie plugin still work or not?? any way to make cookies work?

  23. R H

    Hmm, if cookies do not work, then could a jquery cookie plugin still work or not?? any way to make cookies work?

  24. Could you guys please add the necessary mime types for this hosting so that click once would work. As stated at it would be ideal if you could add 

    .application –> application/x-ms-application
    .manifest –> application/x-ms-manifest
    .deploy –> application/octet-stream
    .msp –> application/octet-stream
    .msu –> application/octet-stream
    .vsto –> application/x-ms-vsto
    .xaml –> application/xaml+xml
    .xbap –> application/x-ms-xbap

    I've tried to add these by adding a .htaccess file in my repository but that does not seem to work...

    Thanks (smile)

    1. Hello and thanks for posting!

      I was going to suggest opening a feature request issue for this, but I see you already have: here. So, thanks!

      People can click on the link above and vote on this issue.

      Have an exceptional day!

      1. Thanks Dan, I did log it, but there has been absolutely no movement since then. How long does a simple request like this take?

      2. Wow still nothing on this? and I gave you guys the text to just copy paste?!

  25. pages seem to have the http header 'X-Frame-Options' set to same origin, is this deliberate? I am trying to iframe content from one of these sites and with that header it wont work. Heres why I want to do it btw

    1. Good day Brian,

      Thanks for taking the time to comment and sorry for taking so long to reply. 

      We currently set header that way to prevent clickjacking. Of course we want to encourage your awesome site but I don't have a solution for this at the moment.

      I hope this helps, or at least answers your question.

  26. A custom 404 error page may be much more useful than the default one. Is it available that I customize a 404.html as my site`s error page?

  27. This article does not support reality. When I click the "Create Repository" button in BitBucket, there seems to be no way to create a repository of the form "" - all I can do is create a repository of the form

    Documentation that says what to do, but not how to do it is very frustrating.

    1. I created a repo called "" for our Conquer Documentation

      I cloned it, added index.html and friends, committed and pushed back to origin.

      I go to "" and I get 404

      So, what am I doing wrong?

      This was so much easier to do in GitHub, but I don't want to use my personal GitHub account to host these pages.

      1. I apologize Eric. I think I was misleading in my earlier post.

        The repository name must contain the your account name or team name in the form: or

        This is what is causing your 404 error. (sad)

        You might consider creating a team with the name:

        Which appears to be available and would allow you to have the url when you create a repo with the name with the team as owner. 

        You could also create an account with that naming convention to achieve the same goal.

        I'm sorry I was not very clear in my earlier post and I hope this helps.

        Happy coding,


        1. OK, success!

          Here are some instructions that I think make sense:

          1. You will need an existing account/team name, for example 'foobar'
            1. Or create a new teamname that is not already in use
          2. Create the repository ''
          3. Add your index.html file (and friends) to the repo.
            1. Clone the repo to your local system.
            2. Add index.html and friends
            3. Commit
            4. Push to origin
          4. Check the results at

          I think that is pretty clear and simple.

  28. Hi,

    If we're a team and we want to create a web site to one of our project can we use the project's name?


    The name is linked to the project's name not to a specific user's name.

    Is this possible?


    1. No, I'm sorry but you cannot.

      The repo (and therefore the URL) must be or
      It might be inconvenient but you could create a new team with the project name and keep less than 5 users with access to the repo (if private) for the website. Or just make it a public repo.

      Hope that helps.

      Happy coding,


  29. Hello everybody! Great feature!
    I need help with one thing though: I would like to index my personal webpage in Google Analytics, I am not able to set things properly. I copied the tracking id in the settings of my Bitbucket repository, however the Google analytics page keeps saying "tracking not installed". Should I write "" as website to monitor?
    Thank you very much

  30. Great feature! Thanks. Just one query. IF I ever delete this site or the repository, can I create another site at the same address?

    1. The domain name is tied to the repository. If you delete the repository, the site will be gone. If you recreate the repository, it'll work again.

  31. Hello 

    Like to ask for some help with setting up the site.

    My username is bybosslee and the repo is set as
    I also setup a simple index.html file at the root.

    However, I still getting the following. "Oops, you've found a dead link."

    What am I doing wrong? Thank you 


      1. Why is everybody ignoring my questions, but answering others? Could I please get an actual answer for the mime types I asked a year ago?

        1. Given the attachment of an issue, it would normally be assumed that the conversation is taking place there. The lack of conversation is unfortunate and I've added a comment/status update to the issue you've raised.

        1. I have similar problem. How you resolved yours? 

  32. I have followed the instructions here Publishing a Website on Bitbucket

    I am not able to get my index.html to show.

    Is this even supported anymore?

    I have it set to

    why does this not work? I get a 403, A valid access token is required to view this resource.

    This also doesn't work but gets a 404

    Do I need to setup a new team?

    The goal here is to point our caching CDN website to point to Bitbucket for my static css, images and js files.



    in a since I want this to show me a website and load the css and images from this repo.


  33. did you create project? is important part of name !!!

  34. Dear guys,

    I created a repo with my account name and already have put an index.html to this repo.  However it still said this is a deadline.

    Do you guys have any idea why it happened?

    Thanks a lot!


    1. Did you name the repo "techpacker" or ""? The domain name must be part of the repo name.

      1. Dear Erik,

        I name the repo "techpacker".  


        1. Yes, but as stated on this page, that is incorrect.

          The repo MUST be named The domain name MUST be part of it.

  35. Could you clarify how to create a folder structure? I have just two existing repositories, one of which is just the account named one to get the static website working. I want the other one as a subfolder (and future ones as further subfolders) but I don't understand how I can have an existing repository work when looking at the instructions "placing each project in a repository subdirectory"?

  36. Is there any config file in the works or currently available?  Something to handle redirects, clean urls (/about.html vs /about), etc.  I think there could be some pretty handy features out there that may be relatively easy to implement.  I'm mostly interested in clean urls at this point.  For the simple config options I would like to see, check out as that's what I've played with in the past, but am very fond of Bitbucket (smile)

  37. As of last week, Aerobatic now provides a Bitbucket add-on that enables Bitbucket users to deploy websites from within the Bitbucket UI. Full version history, custom domains, and git push integration are all part of the initial release, with more features to follow soon. Add-on information can be found here: Cheers!

    1. Hi,

      I try to deploy an app with TiddlyWiki (a single html file contain CCS and JavaScript) but I have this error Uncaught SyntaxError: Unexpected token \ related to JavaScript. In other browsers nothing appear.

      You can have a look here and sources are here

      Is there limitations with JavaScript?

      1. We don't impose any limitations on JavaScript. However, in the case of TiddlyWiki, we have identified the issue and expect to deploy a fix in the new couple of days. Feel free to email us at orville@aerobatic.ioand we can notify you when we've deployed the fix. Thanks.

      2. Hi svink,

        We've deployed a fix to Aerobatic that resolves this issue. Your site renders correctly now.

        Thanks for your feedback.


        1. It's work like a charm!