Setup CI

Start your CI setup by getting a Bit token that has access to the relevant scopes.
You can create a dedicated user such as dev@company.com for the deployment, or use an existing user's token.

To generate a token that does not expire on local logins (in case you chose to use a token that belongs to an existing user), follow the steps described here.

To get your token run the following command:

Run the following to get your token:

$bit config get user.token

Copied

Set user.token as an environment parameter on your server named BIT_TOKEN.

To ensure a component is built and published in a consistent manner its recommended to use CI.
The tag command versions components, but as this is a local command, we need to provide it with the parameters to run on a remote server. Bit features a soft and persist options for tag to manage a remote runs for component versioning as follows:

1. In your project run bit tag with the --soft option to annotate that modified components should be versioned and exported.
2. Bit will update .bitmap with information on which components should be versioned.
3. Commit changes and publish a pull request to your Git repository.
4. Get results of the PR build and collaborate on the soon-to-be published components.
5. Merge changes to main branch.
6. CI versions all marked components and publish them.
7. CI commits back to the repository the updated .bitmap in a post-export state.

Below are the steps you should follow to automate component export.

Your CI container should have Bit installed and authenticated with your remote Bit server(s). You can use bvm to install Bit.
Authenticating Bit depends on how you host your Bit servers. If using a self-hosted Bit server you should manage authentication as you set it up for yourself.
If using bit.cloud grab your authentication token by running bit config after you ran bit login.

When your feature branch is done and you want to mark which components are published, their next version and a changelog message use --soft option.

$bit tag --message "my message" --soft

Copied

Bit then update .bitmap for all modified components and their dependents with the new version and the changelog message. Commit changes and push your branch.

$git commit -am "my message" && git push

Copied

It is recommended to verify there aren't any issues found in your workspace components, before running the tag/build pipeline. Use the strict option to exit with code 1 when issues are found (use this exit code to stop the CI):

$bit status --strict

Copied

When developing in a local workspace Bit prioritize performance and dev experience for the test and build process of each component. When you open a PR with changes to components it's recommended for Bit to run the entire isolation process for each component. To run a component complete build pipeline and have Bit ensure component isolation run the build command:

$bit build

Copied

Use the PR to collaborate on components and merge changes to main branch.

When soft-tagged components are merged to the main branch your CI should run the tag command to version and publish the components.

$bit tag --persist

Copied

After new versions are persisted to Bit's storage you can safely export:

$bit export

Copied

The following steps will update the .bitmap file. It's important to commit back these changes to the repository.

$git add .bitmap

Copied

$git commit -m "update .bitmap with new component versions (automated). [skip-ci]"

Copied

$git push

Copied

Below are some examples/references to help you get started with your CI.

You can also follow along with this example project.

1. Create a new secret variable in your Github repository. Name it BIT_TOKEN and set the value of it to the user.token value.
2. Create a new tag-and-export.yml file in your remote repository ./.github/workflows directory.
3. Create your script.

Here's a demo script you can start with:

# This workflow hard-tags and exports soft-tagged components
name: Tag and Export Components

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  tag-and-export:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '--skip-ci')"
    env:
      BIT_TOKEN: ${{ secrets.BIT_TOKEN }}

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js 12
        uses: actions/setup-node@v1
        with:
          node-version: 12.x
      - name: Install Bit Version Manager
        run: npm i -g @teambit/bvm
      - name: Install latest Bit version
        run: bvm install
      - name: add bvm bin folder to path
        run: echo "$HOME/bin" >> $GITHUB_PATH
      - name: Set up bit config
        run: |
          bit config set analytics_reporting false
          bit config set anonymous_reporting false
          bit config set user.token $BIT_TOKEN
      - name: Install packages using bit
        run: bit install
      - name: Hard-tag pending components
        run: bit tag --persist
      - name: Export components
        run: bit export
      - name: Commit changes made to .bitmap
        run: |
          git config --global user.name '${{ github.actor }}'
          git config --global user.email '${{ github.actor }}@users.noreply.github.com'
          git add .bitmap
          git commit -m "update .bitmap with new component versions (automated). --skip-ci"
          git push
Copied

1. Generate a Personal Access Token with "Read Repository" and "Write Repository" permissions (this will be GL_TOKEN).
2. Generate BIT_TOKEN by grabbing it from your local "bit config" output.
3. Configure both tokens as project variables for your GitLab project and name them GL_TOKEN and BIT_USER_TOKEN.
4. Create a .gitlab-ci.yml file in the root of the repository.
5. Create your script.

Here's a demo script you can start with:

publish_components:
  image: node:latest
  only: master
  script:
    # Install Bit and configure permissions
    - npm i -g @teambit/bvm
    - bvm install
    - export PATH=$HOME/bin:$PATH
    - bit config set analytics_reporting false
    - bit config set anonymous_reporting false
    - bit config set user.token $BIT_TOKEN
    # Install dependencies
    - bit install
    # Version all pending components
    - bit tag --persist
    # Export components
    - bit export
    # Setup Git and commit back .bitmap changes
    - git config --global user.email "some@email.address"
    - git config --global user.name "some ci account"
    - export GL_RELEASE_GITLAB_API_TOKEN=$GL_TOKEN
    # This checkout is a workaround for the "error: src refspec master does not match any." error
    - git checkout master
    # Add the modified ".bitmap" file
    - git add .
    # Replace origin with authenticated origin
    - git remote rm origin
    - git remote add origin https://[repo-owner]:$GL_RELEASE_GITLAB_API_TOKEN@gitlab.com/[repo-ower]/[repo-name].git
    # Using [skip ci] as its a feature for GitLab that will not trigger CI for this commit
    - git commit -am 'publish components [skip ci]'
    - git pull origin master
    - git push origin master
Copied

Bit components are stored on the bit registry located in https://node.bit.cloud.

When installing components with npm or yarn, they will try to install the components starting with @<account-name> by resolving the @<account-name> registry. This configuration is stored in an .npmrc configuration file. Npm and yarn respect the following file locations:

• per-project config file (/path/to/my/project/.npmrc)
• per-user config file (~/.npmrc)
• global config file ($PREFIX/etc/npmrc)
• npm builtin config file (/path/to/npm/npmrc)

When working locally, bit login configures this file automatically for you. You will need to set this file manually for your CI. If not done right you will get these errors:

NPM

failed running npm install at /Users/user/devenv/example-npm-error/components/utils/string/pad-left
npm ERR! code E404
npm ERR! 404 Not Found: @teambit/utils.string.pad-left@0.0.1
Copied

Yarn

failed running yarn install at /Users/user/devenv/example-npm-error/components/utils/string/pad-left
error An unexpected error occurred: "https://registry.yarnpkg.com/@teambit%2fbit.utils.string.pad-left: Not found".
Copied

The error is solved by making sure that one of the .npmrc files has the configuration prior to running npm install. The solutions vary per vendor (see below), but the main methods are:

• Define .npmrc in the project.
• Generate .npmrc file for the CI user
• Extend .npmrc configuration with vendor's tools

You can add a .npmrc in your project with the following:

@<account-name>:registry=https://node.bit.cloud
@teambit:registry=https://node.bit.cloud
//node.bit.cloud/:_authToken=${BIT_TOKEN}
always-auth=true
Copied

Define BIT_TOKEN as a secret global variable on the server.

Run the following script to generate the .npmrc file, dynamically (e.g. create a bit_npm.sh script):

echo "Adding bit.cloud to npm registry"
echo "always-auth=true" >> ~/.npmrc
echo "@<account-name>:registry=https://node.bit.cloud" >> ~/.npmrc
echo "@teambit:registry=https:/node.bit.cloud" >> ~/.npmrc
echo "//node.bit.cloud/:_authToken={$BIT_TOKEN}" >> ~/.npmrc
echo "Completed adding bit.cloud to npm registry"
Copied

On Netlify, you cannot generate the file dynamically. Instead, manually add the .npmrc file to your project.

Add the BIT_TOKEN as environment variable

Learn how to use private dependencies with Vercel and add the contents of your ~/.npmrc file as an environment variable.

In .gitlab-ci.yml run the script that generates the file for the user as an initial step before running npm install.

Add the BIT_TOKEN as an environment variable

Add the BIT_TOKEN as a secret in GitHub.

In the GitHub workflow file, create a step before the npm install section:

- name: init bit.cloud
  run: |
    echo "Adding bit.cloud to npm registry"
    npm config set @<owner>:registry=https://node.bit.cloud
    npm config set @teambit:registry=https://node.bit.cloud
    npm config set //node.bit.cloud/:_authToken ${BIT_TOKEN}
    echo "Completed adding bit.cloud to npm registry"
  env:
    BIT_TOKEN: ${{ secrets.BIT_TOKEN }}
Copied

To generate the .npmrc before installing dependencies, run a pre-build script as described here.

Add the BIT_TOKEN as an environment variable

Use the npm authenticate task to setup the .npmrc configuration in your pipeline.

- script: |
      npm i -g @teambit/bvm
      bvm install
      export PATH=$HOME/bin:$PATH
      bit config set analytics_reporting false
      bit config set anonymous_reporting false
      bit config set user.token $(BIT_TOKEN)
      bit config

      bit install
      bit compile
      bit tag --persist
      bit export
    displayName: "bit export to private collection"

  - script: |
      git config --global user.email "my@email.domain"
      git config --global user.name "BuildService"
      git checkout main
      git add .
      git commit -m "new version [skip ci]"
      git push -u origin main
    displayName: "git commit back after exported new version components"
Copied

NPM or Yarn throws 'package not found' when importing a component. This is likely because the component has a dependency on a @bit component. Make sure npmrc is configured.

Possible reasons:

• npmrc is not properly configured
• You do not have the right permissions on the scope that the components are hosted in, and are therefore unable to access its components. Make sure you have at least read permissions for the scope that host the components.
• Yarn does not send an authentication token when installing packages from a yarn.lock file. This is a known issue. Make sure always-auth is configured in .npmrc.